Skip to content

Windows

Jump to bottom
Eric edited this page Nov 5, 2024 · 123 revisions

In OGX.JS, windows are draggable sliding panels. If you wish to create a window like you would see in an operating system environment, you should use a popup.

Windows can have static or relative sizes, a main icon, a toolbar with icons, a title, a head bar and a view.

Stack

Windows by default extend

  Uxi, Touch;

Complete stack

  Uxi, Touch, Overlay, Loading

Instantiate

 let config = {  
    id:_UNIQUE_STRING_, //Required, name of window       
    width: _WIDTH_% | _WIDTH_px, //Required
    min_width:_INT_, //Optional,
    max_width:_INT_, //Optional
    min_height:_INT_, //Optional
    max_height:_INT_, //Optional
    title:_STRING_, //optional,
    scroll: true|false, //Optional, defaults to false,       
    blur: true|false, //Optional, defaults to true, if the Window handles views blur/focus       
    html: _STRING_, //Optional, HTML string to append to the view of the window
    template: _STRING_, //Optional, HTML template to append to the view of the window
    view:_OBJECT_, //Optional, the view object to be instanced in the default container of the window
    css: _CUSTOM_CSS_CLASS_,
    head: OGX.Window.HEAD_NONE |
           OGX.Window.HEAD_CLOSE |
           OGX.Window.HEAD_BACK, //Optional, defaults to OGX.Window.STYLE_NONE
    anim: OGX.Window.ANIM_LEFT | 
               OGX.Window.ANIM_RIGHT | 
               OGX.Window.ANIM_TOP | 
               OGX.Window.ANIM_BOTTOM, //Optional, default to 
    zindex: _INT_ ///Optional,
    icon:_STRING_ //Optional,
    icons:_ARRAY_ //Optional,
    data: _OBJECT_ //Optional, if set, will be interpreted as `{{$}}` at `OML` rendering
 }; 
 let win = app.addWindow(config);

Example - create a window on current stage of 50% screen width, with no head and without showing it:

 let config = {       
    id:'myWindow',
    head: OGX.Window.HEAD_NONE, //or 'none'
    width: '50%'       
 };  
 let win = app.addWindow(config);

Create the same window inside/from a Uxi

 let win = this.addWindow(config);

Example - create a window of 300px width with a scrollable body and a 'BACK' head style and show it right away animating it (slide) coming FROM the LEFT

let config = {
    id:'myWindow',
    head: OGX.Window.HEAD_BACK, //or 'back'
    width: '300px',
    anim: OGX.Window.ANIM_LEFT,
    scroll:true     
};
let win = app.addWindow(config);

Note that you can also use the value of the constant for the animation, such as 'left', 'right', 'top' or 'bottom'. Using the constant is recommended though in case of future changes.

Size

Window supports size expressions. Size can be passed as number or string (with or without unit). For more info about this, check out the Data component.

 width:'300px|600|100%';

Content

Windows rely on OML to create a content inside of them. Each Window only has 1 placeholder, the body of the Window, into which, you can render any OML tree

 let config = {       
    id:'myWindow',
    head: 'back',
    width:'50%',
    'node:OML':[
         {'default:Html':{
              html:'<span class="whatever">Hello!</span>'
         }}
    ]    
 };  
 let win = app.addWindow(config);

Using OML to create a Container

 let config = {       
    id:'myWindow',
    head: 'back',
    width:'50%',
    'node:OML':[
         {'default:Container':{
              tabs:false,
              'node:OML':[
                   {'default:Html':{
                        html:'<span class="whatever">View A</span>'
                   }},
                   {'default:Html':{
                        html:'<span class="whatever">View B</span>'
                   }}
              ]
         }}
     ]    
 };  
 let win = app.addWindow(config);

OML content as OML file

 let config = {       
    id:'myWindow',
    head: 'back',
    width:'50%',
    'node:OML':'{{oml myFile}}'  
 };  
 let win = app.addWindow(config);

Get/Set

Get the OGX.Window instance by passing its id

let win = app.getWindow(_ID_); //Get the OGX.Window instance by passing its name

Get an array of names of all existing windows (for the stage in use). You can pass a string or a regular expression to only search for specific names.

let names = app.getWindows(_SEARCH_); //Search is optional

Check if a window exists

app.windowExists(_ID_);

Find the window from a Uxi instanced within the window

app.findWindow(this);

Check if a window is open

app.windowOpen(_ID_);

The blur method is automatically called when a window becomes fully hidden. The focus method is called when the window becomes fully shown. You still have access to blur or focus any window at anytime. It is highly recommended to use these methods in the OGX.View that embedded inside a window, since they will be triggered too.

The idea behind it is to turn off any listeners when the window is blurred to save on memory.

Snooze/Wake

app.snoozeWindow(_ID_);
app.wakeWindow(_ID_);

Snoozing a window will blur it as well but also detach it (off of the DOM) and becomes fully unavailable programmatically.

Waking a window will re-attach the window and call focus upon it.

Open

 //Create and open
 let win = app.addWindow(_CONFIG_);
 
 //Show/Open existing window
 app.showWindow(_ID_, _ANIM_, _CALLBACK_, _PARAMS_);

 //Find then show
 app.find('Window', _ID_).show();

Close

 app.hideWindow(_ID_, _ANIM_, _CALLBACK_, _PARAMS_);

The callback is optional and expect a function to be called once the window is fully hidden. If no animation is passed (or set to true), the animation used to show the window will be reused.

Hide a window reusing its set animation

 app.hideWindow('myWindow');

Hide a window without animation

 app.hideWindow('myWindow', false);

You can also hide a window directly from a view within than window by doing

 app.hideWindow(this);

You can remove the window once it is hidden by doing

 app.hideWindow('myWindow', true, function(){
      app.removeWindow('myWindow);
 });

Find then hide using set animation

 app.find('Window', _ID_).hide();

Remove

 app.removeWindow(_ID_);
 app.removeWindows(_ARRAY_OF_WINDOW_IDS_);

Removing (deleting) a window triggers the destroy method of ALL views embedded in the window.

You can also remove all windows form a stage

 app.removeAllWindows();

And also remove all windows but some

 app.removeAllWindows(['myWindow']);

Swap

 app.swapWindows(_WINDOW_A_, _WINDOW_B_);

Swaps the z-index between two windows.

Drag 1.9.3+

You can set up your Window to be draggable from the config and/or override it at runtime

 app.cfind('Window', _ID_).drag(true|false);

Overlay

You can also add an INNER overlay, for instance, if you need to display a loading effect.

 let win = app.getWindow('MyWindow');
 win.addOverlay(_FADE_BOOLEAN_); //Defaults to true

Adds an overlay over the view of the window. Optional Boolean parameter to fade the overlay or not.

 win.removeOverlay();

Removes the overlay

Title 1.30.0+

You can set the title on the fly

let win = app.getWindow('MyWindow');
win.title('My Title');

Icons

Windows can have a multiple icons. The top left corner icon of the popup is set with the property icon of the config (path to icon file). It is optional. You can also add interactive icons in the top right corner of the popup, by passing an array of icons such as:

 let config = {..., icon:'path_to_image', icons:[
     {icon:'path_to_imageA', callback:_FUNCTION_},
     {icon:'path_to_imageB', callback:_FUNCTION_},
 ]};

The function linked to the callback parameter will be called when the end user hits it.

You can also get/set icons on the fly using the icons method

 myWindow.icons([{icon:'path_to_imageA', callback:_FUNCTION_},{icon:'path_to_imageA', callback:_FUNCTION_}]);

If you'd rather listen for the OGX.Window.HIT_ICON event, you can simply set your icons as

 myWindow.icons(['path_to_imageA', 'path_to_imageA']);

Events

 OGX.Window.CLOSING;
 OGX.Window.CLOSED;
 OGX.Window.OPENING;
 OGX.Window.OPEN;
 OGX.Window.HIT_ICON;
 OGX.Window.HIT_BACK;
Clone this wiki locally