<commit_before># Events

Think of event functions as _state changers_. Their only job is to react to triggers (such as user interactions and program events) and make modifications to the component's state.

## Events structure

When adding events to a component, organize them within objects grouped by _selectors_ (use [CSS style selectors](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors)):

    FamousFramework.component('example', {
        events: {
            'selector1': {
            	'event-name1': function() {
            	    // do something
            	},
            	'event-name2': function(){
            	    // do something else
            	}
            },
            'selector2': {
                'event-name1': function(){
                    // do something else here
                }	
            }
        }
    });

The event object selectors specify which event functions will be attached to the corresponding elements in the tree. Event listeners can be either be traditional DOM events ('click', 'mousedown', etc) or custom programmatic events. 

## Modifying the state

Events, and only events, can modify a module's [state](states.md) values. Via dependency injection, event functions can read and write to these values through the `$state` object.

    FamousFramework.component('example', {
        events: {
            '.nav-button': {
                'click': function($state, $payload) {
                     // get the 'clickCount' value (zero)
                     var oldValue = $state.get('clickCount');
                     // increment the counter by 5 
                     $state.set('clickCount', oldValue + 5);
                }
            }  	 
        },
        states: {
        	clickCount: 0 // will increment by 5 on a click
        }
    });

Here, we use `$state.get()` to grab the state value for `clickCount` and the `.set()` method to replace it with a new incremented value. This event function will run every time a `'.nav-button'` element is clicked. 

It's common to dependency-inject a `$state` instance along with a complementary `$payload` object, which is the message accompanying the source event. In the example above, the `$payload` would be a [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object.

_For more on the `$state` object's API visit the [states section](states.md)._

## Custom events

To emit a custom event message, you'll need to dependency-inject a `$dispatcher` instance into your event function:

    FamousFramework.component('example', {
        events: {
            '$public': {
                'something': function($dispatcher) {
                    $dispatcher.emit('hello', 'my message');
                }
            }
        }
    });

Components can listen to messages emitted by any component declared in their tree.

    FamousFramework.component('example', {
        events: {
            '#foo': {
                // This will run any time a tree node matching '#foo'
                // emits a message whose key is 'hello'.
                'hello': function($payload) {
                    // Do business logic here
                }
            }
        },
        tree: `<node id="foo"></node>`
    });

## $lifecycle events

The `$lifecycle` event group allows you to listen for special events throughout the life of a component. To access these events, provide `'$lifecycle'` as a selector to the events object instead of a selector.

Here, we set the state's `positionX` value to `250` over a 1000ms period immediately after the component loads.
  
    FamousFramework.component('example', {
		events: {
	        '$lifecycle': {
	            'post-load': function($state) {
	                $state.set('positionX', 250, { duration:1000 });
	            }
	        }
		}
    });

`$lifecycle` events include:

- `'post-load'`
- `'pre-unload'`

## Private vs. public events

Events within the `$private` group will only be triggered by a scene's own `$self` behaviors.
<commit_msg>docs: Add size-change + parent-size-change docs<commit_after># Events

Think of event functions as _state changers_. Their only job is to react to triggers (such as user interactions and program events) and make modifications to the component's state.

## Events structure

When adding events to a component, organize them within objects grouped by _selectors_ (use [CSS style selectors](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Getting_Started/Selectors)):

    FamousFramework.component('example', {
        events: {
            'selector1': {
            	'event-name1': function() {
            	    // do something
            	},
            	'event-name2': function(){
            	    // do something else
            	}
            },
            'selector2': {
                'event-name1': function(){
                    // do something else here
                }	
            }
        }
    });

The event object selectors specify which event functions will be attached to the corresponding elements in the tree. Event listeners can be either be traditional DOM events ('click', 'mousedown', etc) or custom programmatic events. 

## Modifying the state

Events, and only events, can modify a module's [state](states.md) values. Via dependency injection, event functions can read and write to these values through the `$state` object.

    FamousFramework.component('example', {
        events: {
            '.nav-button': {
                'click': function($state, $payload) {
                     // get the 'clickCount' value (zero)
                     var oldValue = $state.get('clickCount');
                     // increment the counter by 5 
                     $state.set('clickCount', oldValue + 5);
                }
            }  	 
        },
        states: {
        	clickCount: 0 // will increment by 5 on a click
        }
    });

Here, we use `$state.get()` to grab the state value for `clickCount` and the `.set()` method to replace it with a new incremented value. This event function will run every time a `'.nav-button'` element is clicked. 

It's common to dependency-inject a `$state` instance along with a complementary `$payload` object, which is the message accompanying the source event. In the example above, the `$payload` would be a [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object.

_For more on the `$state` object's API visit the [states section](states.md)._

## Custom events

To emit a custom event message, you'll need to dependency-inject a `$dispatcher` instance into your event function:

    FamousFramework.component('example', {
        events: {
            '$public': {
                'something': function($dispatcher) {
                    $dispatcher.emit('hello', 'my message');
                }
            }
        }
    });

Components can listen to messages emitted by any component declared in their tree.

    FamousFramework.component('example', {
        events: {
            '#foo': {
                // This will run any time a tree node matching '#foo'
                // emits a message whose key is 'hello'.
                'hello': function($payload) {
                    // Do business logic here
                }
            }
        },
        tree: `<node id="foo"></node>`
    });

## Size change events

Size change event group allows you to listen for changes in a component's size or a component's  
parent's size. To access these events, target an element in your tree as a selector.

    FamousFramework.component('example', {
        events: {
            '.child-square': {
                'size-change': function($event) {
                    var ownSize = $event.value;
                    // The child-square's new width is ownSize[0]
                    // The child-square's new height is ownSize[1]
                },
                'parent-size-change': function($event) {
                    var parentSize = $event.value;
                    // The parent-square's new width is parentSize[0]
                    // The parent-square's new height is parentSize[1]
                }
            }
        },
        tree: `
            <node class="parent-square">
                <node class="child-square"></node>
            </node>
        `
    });

Size change events include:
- `'size-change'`
- `'parent-size-change'`

## $lifecycle events

The `$lifecycle` event group allows you to listen for special events throughout the life of a component. To access these events, provide `'$lifecycle'` as a selector to the events object instead of a selector.

Here, we set the state's `positionX` value to `250` over a 1000ms period immediately after the component loads.
  
    FamousFramework.component('example', {
		events: {
	        '$lifecycle': {
	            'post-load': function($state) {
	                $state.set('positionX', 250, { duration:1000 });
	            }
	        }
		}
    });

`$lifecycle` events include:

- `'post-load'`
- `'pre-unload'`

## Private vs. public events

Events within the `$private` group will only be triggered by a scene's own `$self` behaviors.

{'fraction_non_alphanumeric': 0.10380021715526601, 'fraction_numerical': 0.0054288816503800215, 'mean_word_length': 2.040937603169363, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7181582', 'n_tokens_mistral': 2456, 'n_tokens_neox': 2297, 'n_words': 882}