Many classes have shortcut names used when creating (instantiating) a class with a
configuration object. The shortcut name is referred to as an alias (or xtype if the
class extends Ext.Component). The alias/xtype is listed next to the class name of
applicable classes for quick reference.
Framework classes or their members may be specified as private or protected. Else,
the class / member is public. Public, protected, and private are access
descriptors used to convey how and when the class or class member should be used.
Public classes and class members are available for use by any other class or application code and may be relied upon as a stable and persistent within major product versions. Public classes and members may safely be extended via a subclass.
Protected class members are stable public members intended to be used by the
owning class or its subclasses. Protected members may safely be extended via a subclass.
Private classes and class members are used internally by the framework and are not intended to be used by application developers. Private classes and members may change or be omitted from the framework at any time without notice and should not be relied upon in application logic.
static label next to the
method name. *See Static below.Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).
Let's look at each part of the member row:
lookupComponent in this example)( item ) in this example)Ext.Component in this case). This may be omitted for methods that do not
return anything other than undefined or may display as multiple possible values
separated by a forward slash / signifying that what is returned may depend on the
results of the method call (i.e. a method may return a Component if a get method calls is
successful or false if unsuccessful which would be displayed as
Ext.Component/Boolean).PROTECTED in
this example - see the Flags section below)Ext.container.Container in this example). The source
class will be displayed as a blue link if the member originates from the current class
and gray if it is inherited from an ancestor or mixed-in class.view source in the example)item : Object in the example).undefined a "Returns" section
will note the type of class or object returned and a description (Ext.Component in the
example)Available since 3.4.0 - not pictured in
the example) just after the member descriptionDefaults to: false)The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.
classInstance.method1().method2().etc();false is returned from
an event handler- Indicates a framework class
- A singleton framework class. *See the singleton flag for more information
- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)
- Indicates that the class, member, or guide is new in the currently viewed version
- Indicates a class member of type config
- Indicates a class member of type property
- Indicates a class member of type
method
- Indicates a class member of type event
- Indicates a class member of type
theme variable
- Indicates a class member of type
theme mixin
- Indicates that the class, member, or guide is new in the currently viewed version
Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.
Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.
Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.
Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.
If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.
Both API docs and guides can be searched for using the search field at the top of the page.
On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level, inheritance, and read only. This is done using the checkboxes at the top of the page.
The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.
Clicking on an empty search field will show your last 10 searches for quick navigation.
Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:
Ext.button.Button class has an alternate class name of Ext.Button). Alternate class
names are commonly maintained for backward compatibility.Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.
Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.
Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:
The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.
Manages context information during a layout.
This class performs the following jobs:
Work done during layout falls into either a "read phase" or a "write phase" and it is essential to always be aware of the current phase. Most methods in Ext.layout.Layout are called during a read phase: calculate, completeLayout and finalizeLayout. The exceptions to this are beginLayout, beginLayoutCycle and finishedLayout which are called during a write phase. While finishedLayout is called a write phase, it is really intended to be a catch-all for post-processing after a layout run.
In a read phase, it is OK to read the DOM but this should be done using the appropriate Ext.layout.ContextItem where possible since that provides a cache to avoid redundant reads. No writes should be made to the DOM in a read phase! Instead, the values should be written to the proper ContextItem for later write-back.
The rules flip-flop in a write phase. The only difference is that ContextItem methods like getStyle will still read the DOM unless the value was previously read. This detail is unknowable from the outside of ContextItem, so read calls to ContextItem should also be avoided in a write phase.
Calculating interdependent layouts requires a certain amount of iteration. In a given cycle, some layouts will contribute results that allow other layouts to proceed. The general flow then is to gather all of the layouts (both component and container) in a component tree and queue them all for processing. The initial queue order is bottom-up and component layout first, then container layout (if applicable) for each component.
This initial step also calls the beginLayout method on all layouts to clear any values from the DOM that might interfere with calculations and measurements. In other words, this is a "write phase" and reads from the DOM should be strictly avoided.
Next the layout enters into its iterations or "cycles". Each cycle consists of calling the calculate method on all layouts in the layoutQueue. These calls are part of a "read phase" and writes to the DOM should be strictly avoided.
RULE 1: Respect the read/write cycles. Always use the getProp or getDomProp methods to get calculated values; only use the getStyle method to read styles; use setProp to set DOM values. Some reads will, of course, still go directly to the DOM, but if there is a method in Ext.layout.ContextItem to do a certain job, it should be used instead of a lower-level equivalent.
The basic logic flow in calculate consists of gathering
values by calling getProp or
getDomProp, calculating results and publishing
them by calling setProp. It is important to realize
that getProp will return undefined if the value
is not yet known. But the act of calling the method is enough to track the fact that the
calling layout depends (in some way) on this value. In other words, the calling layout is
"triggered" by the properties it requests.
RULE 2: Avoid calling getProp unless the value is needed. Gratuitous calls cause inefficiency because the layout will appear to depend on values that it never actually uses. This applies equally to getDomProp and the test-only methods hasProp and hasDomProp.
Because getProp can return undefined, it is often
the case that subsequent math will produce NaN's. This is usually not a problem as the
NaN's simply propagate along and result in final results that are NaN. Both undefined
and NaN are ignored by Ext.layout.ContextItem#setProp, so it is often not necessary
to even know that this is happening. It does become important for determining if a layout
is not done or if it might lead to publishing an incorrect (but not NaN or undefined)
value.
RULE 3: If a layout has not calculated all the values it is required to calculate, it
must set done to false before returning from
calculate. This value is always true on entry because
it is simpler to detect the incomplete state rather than the complete state (especially up
and down a class hierarchy).
RULE 4: A layout must never publish an incomplete (wrong) result. Doing so would cause dependent layouts to run their calculations on those wrong values, producing more wrong values and some layouts may even incorrectly flag themselves as done before the correct values are determined and republished. Doing this will poison the calculations.
RULE 5: Each value should only be published by one layout. If multiple layouts attempt to publish the same values, it would be nearly impossible to avoid breaking RULE 4. To help detect this problem, the layout diagnostics will trap on an attempt to set a value from different layouts.
Complex layouts can produce many results as part of their calculations. These values are important for other layouts to proceed and need to be published by the earliest possible call to Ext.layout.Layout#calculate to avoid unnecessary cycles and poor performance. It is also possible, however, for some results to be related in a way such that publishing them may be an all-or-none proposition (typically to avoid breaking RULE 4).
RULE 6: Publish results as soon as they are known to be correct rather than wait for all values to be calculated. Waiting for everything to be complete can lead to deadlock. The key here is not to forget RULE 4 in the process.
Some layouts depend on certain critical values as part of their calculations. For example, HBox depends on width and cannot do anything until the width is known. In these cases, it is best to use block or domBlock and thereby avoid processing the layout until the needed value is available.
RULE 7: Use block or domBlock when values are required to make progress. This will mimize wasted recalculations.
RULE 8: Blocks should only be used when no forward progress can be made. If even one value could still be calculated, a block could result in a deadlock.
Historically, layouts have been invoked directly by component code, sometimes in places
like an afterLayout method for a child component. With the flexibility now available
to solve complex, iterative issues, such things should be done in a responsible layout
(be it component or container).
RULE 9: Use layouts to solve layout issues and don't wait for the layout to finish to perform further layouts. This is especially important now that layouts process entire component trees and not each layout in isolation.
The simplest sequence diagram for a layout run looks roughly like this:
Context Layout 1 Item 1 Layout 2 Item 2
| | | | |
---->X-------------->X | | |
run X---------------|-----------|---------->X |
X beginLayout | | | |
X | | | |
A X-------------->X | | |
X calculate X---------->X | |
X C X getProp | | |
B X X---------->X | |
X | setProp | | |
X | | | |
D X---------------|-----------|---------->X |
X calculate | | X---------->X
X | | | setProp |
E X | | | |
X---------------|-----------|---------->X |
X completeLayout| | F | |
X | | | |
G X | | | |
H X-------------->X | | |
X calculate X---------->X | |
X I X getProp | | |
X X---------->X | |
X | setProp | | |
J X-------------->X | | |
X completeLayout| | | |
X | | | |
K X-------------->X | | |
X---------------|-----------|---------->X |
X finalizeLayout| | | |
X | | | |
L X-------------->X | | |
X---------------|-----------|---------->X |
X finishedLayout| | | |
X | | | |
M X-------------->X | | |
X---------------|-----------|---------->X |
X notifyOwner | | | |
N | | | | |
- - - - -
Notes:
A. This is a call from the run method to the run method. Each layout in the queue will have its calculate method called.
B. After each calculate method is called the done flag is checked to see if the Layout has completed. If it has completed and that layout object implements a completeLayout method, this layout is queued to receive its call. Otherwise, the layout will be queued again unless there are blocks or triggers that govern its requeueing.
C. The call to getProp is made to the Item and that will be tracked as a trigger (keyed by the name of the property being requested). Changes to this property will cause this layout to be requeued. The call to setProp will place a value in the item and not directly into the DOM.
D. Call the other layouts now in the first cycle (repeat B and C for each layout).
E. After completing a cycle, if progress was made (new properties were written to the context) and if the layoutQueue is not empty, the next cycle is run. If no progress was made or no layouts are ready to run, all buffered values are written to the DOM (a flush).
F. After flushing, any layouts that were marked as done that also have a completeLayout method are called. This can cause them to become no longer done (see invalidate). As with calculate, this is considered a "read phase" and direct DOM writes should be avoided.
G. Flushing and calling any pending completeLayout methods will likely trigger layouts that called getDomProp and unblock layouts that have called domBlock. These variants are used when a layout needs the value to be correct in the DOM and not simply known. If this does not cause at least one layout to enter the queue, we have a layout FAILURE. Otherwise, we continue with the next cycle.
H. Call calculate on any layouts in the queue at the start of this cycle. Just a repeat of B through G.
I. Once the layout has calculated all that it is resposible for, it can leave itself in the done state. This is the value on entry to calculate and must be cleared in that call if the layout has more work to do.
J. Now that all layouts are done, flush any DOM values and completeLayout calls. This can again cause layouts to become not done, and so we will be back on another cycle if that happens.
K. After all layouts are done, call the finalizeLayout method on any layouts that have one. As with completeLayout, this can cause layouts to become no longer done. This is less desirable than using completeLayout because it will cause all finalizeLayout methods to be called again when we think things are all wrapped up.
L. After finishing the last iteration, layouts that have a finishedLayout method will be called. This call will only happen once per run and cannot cause layouts to be run further.
M. After calling finahedLayout, layouts that have a notifyOwner method will be called. This call will only happen once per run and cannot cause layouts to be run further.
N. One last flush to make sure everything has been written to the DOM.
Many layout problems require collaboration between multiple layouts. In some cases, this is as simple as a component's container layout providing results used by its component layout or vise-versa. A slightly more distant collaboration occurs in a box layout when stretchmax is used: the child item's component layout provides results that are consumed by the ownerCt's box layout to determine the size of the children.
The various forms of interdependence between a container and its children are described by each components' size model.
To facilitate this collaboration, the following pairs of properties are published to the component's Ext.layout.ContextItem:
Ext JS | Terms of Use