1. Introduction
The Uize.Widget.Dialog.xResizable module extends the Uize.Widget.Dialog base class by adding a highly configurable resizing capability for dialogs.
DEVELOPERS: Chris van Rensburg
The Uize.Widget.Dialog.xResizable module is an extension module that extends the Uize.Widget.Dialog class. In a Rich Internet Application, many dialogs will not need to be resizable by the user. Therefore, the resizability functionality is not implemented in the Uize.Widget.Dialog class - in order to reduce the need for loading the extra code. Instead, in order to make dialogs resizable one needs to require the Uize.Widget.Dialog.xResizable extension module and set the resizable set-get property that it adds to the Uize.Widget.Dialog class to true for any dialogs that you want to be resizable. Consider the following example...
EXAMPLE
Uize.module ({
required:[
'Uize.Widget.Page',
'Uize.Widget.Dialog.xResizable'
],
builder:function () {
var page = window.page = new Uize.Widget.Page;
page.addChild ('resizableDialog',Uize.Widget.Dialog,{resizable:true});
}
});
In the above example, an anonymous module is being used to require the Uize.Widget.Page (page widget) class and the Uize.Widget.Dialog.xResizable extension module. Once these two modules are loaded, the builder function creates an instance of the page widget and adds a dialog (an instance of the Uize.Widget.Dialog class) named resizableDialog as a child widget. By specifying the initial state of {resizable:true}, the dialog is resizable by the user.
1.1. Things to Note
1.1.1. Must Set Resizable To True
It is not sufficient to merely require the Uize.Widget.Dialog.xResizable module in order for dialogs to be resizable.
This module only implements the resizability functionality. You still need to enable resizability for specific dialogs, because just making all dialogs resizable by default would have a runtime cost and may not even be appropriate for most cases.
1.1.2. Requiring Uize.Widget.Dialog Optional
If one requires the Uize.Widget.Dialog.xResizable extension module, it is not essential to require the Uize.Widget.Dialog module, since it is implicit by requiring Uize.Widget.Dialog.xResizable.
However, you may still want to require both as a good practice, since you will technically be creating instances of Uize.Widget.Dialog and not Uize.Widget.Dialog.xResizable.
1.1.3. All Subclasses Resizable
Because the Uize.Widget.Dialog.xResizable module extends the Uize.Widget.Dialog module, instances of all subclasses of Uize.Widget.Dialog will also be able to be resizable.
This is provided that the Uize.Widget.Dialog module is extended before the subclasses are created. Examples of other dialog subclasses include: Uize.Widget.Dialog.Confirm, Uize.Widget.Dialog.Form, and Uize.Widget.Dialog.Form.
1.1.4. Forced Resizable Subclasses
A dialog subclass can be made resizable so that all newly created instances of that subclass will be resizable right off the bat. This is done by setting the value of the resizable set-get property to true on the class, as in the following example...
EXAMPLE
Uize.module ({
required:'Uize.Widget.Dialog.xResizable',
builder:function () {
(MyNamespace.MyDialog = Uize.Widget.Dialog.subclass ()).set ({resizable:true});
var
myDialog1 = new MyNamespace.MyDialog, // resizable
myDialog2 = new MyNamespace.MyDialog ({resizable:false}) // non-resizable
;
}
});
In the above example, instances of the MyNamespace.MyDialog class are automatically resizable. It is still possible to suppress resizability by explicitly setting resizable to false during construction, as is the case with the myDialog2 instance created in this example.
2. Child Widgets
2.1. resizer
An instance of the Uize.Widget.Resizer class, that is used to wire up the resize functionality for the dialog.
The interface of the Uize.Widget.Resizer class can be used to qualify how the dialog is resizable. For example, a dialog could be made only vertically resizable as follows...
Uize.module ({
required:[
'Uize.Widget.Page',
'Uize.Widget.Dialog.xResizable'
],
builder:function () {
var page = window.page = new Uize.Widget.Page;
page.addChild (
'verticallyResizableDialog',Uize.Widget.Dialog,{resizable:true}
).children.resizer.set ({
fixedX:true
});
}
});
In the above example, notice how the resizer child widget is being dereferenced off the children property immediately after adding the dialog child widget. This is possible because the addChild instance method returns a reference to the child widget being added (the dialog in this case). Setting the fixedX set-get property of the resizer instance to true causes the dialog to be resizable only in the Y-axis (vertically).
NOTE: For optimization, the resizer child widget is only created if a dialog is made resizable by setting its resizable set-get property to true. Therefore, be careful to first set a dialog to be resizable before attempting to access the resizer child widget for modifying its state.
3. Set-get Properties
3.1. resizable
A boolean, specifying whether or not the dialog should be resizable.
The value of this property can be changed at any time: before the dialog widget is wired, after it is wired but before it is shown, after it is shown, etc. The first time that this property becomes true, the resizer child widget is added to the dialog widget.
NOTES
the initial value is undefined (equivalent to false) |