OpenXMLDialog()

Syntax

Result = OpenXMLDialog(#Dialog, #XML, Name$ [, x, y [, Width, Height [, ParentID]]])
Description
Open the specified dialog and display it on the screen. To access the dialog gadgets use DialogGadget(). To get the window number of this dialog use DialogWindow().

Parameters

#Dialog The dialog to use. It has to be previously created with CreateDialog().
#XML The xml to use. It has to be previously created with LoadXML(), CreateXML(), CatchXML() or ParseXML(). That means it's possible to create dialogs on the fly with CreateXML(), CatchXML() or ParseXML(). See below for the supported XML attributes. When including XML in the code, it may be easier to use single quote in XML for attribute (it's perfectly legal XML syntax).
Name$ The name of the dialog to open. An XML file can have several dialogs defined.
x, y (optional) The x, y coordinate (in pixels) of the #Dialog.
Width, Height (optional) The size (in pixels) of the #Dialog. If the size is smaller than the required size as defined in the XML (after layout calculation), then the required size will be used. If omitted, the size of the dialog will be the smallest size required.
ParentID (optional) The parent window identifier. A valid window identifier can be retrieved with WindowID().

Return value

Returns nonzero if the dialog has been successfully opened, returns zero otherwise. To get more information about the error which has occurred, use DialogError().

Remarks

----------------------------------------------------------------
   Dialog XML format
----------------------------------------------------------------

  I. Common attributes
  --------------------

  width     - positive integer value or 0 (default="0") (set the "minimum size" of a control)
  height

  id        - #Number identifier for a gadget or a window (default is #PB_Any if not specified). It can be a runtime constant.
  name      - a string identifying the object (for DialogGadget() mainly, case insensitive) (default="")
  text      - text string for the object (default="")

  flags     - gadget/window flags in the form "#PB_Window_Borderless | #PB_Window_ScreenCentered"  (default="")

  min        - minimum value
  max        - maximum value
  value      - current value

  invisible - if set to "yes", creates the object invisible (default="no")
  disabled  - if "yes", creates the object disabled (gadgets only) (default="no")

  colspan   - inside the <gridbox> element only, allows an element to span multiple rows/columns
  rowspan     (default="1")

  All these attributes are optional.


  II. Root element
  ----------------

  <window> for a single window definition in the same XML file
  </window>
  
  or 
    
  <dialogs> for a multiple window definition in the same XML file
    <window name="FirstWindow">
    </window>
    <window name="SecondWindow">
    </window>
    ...
  </dialogs>


  III. Window element
  -------------------

  <window>
  </window>
  
  Accepted keys in the XML: 
  All common attributes and the following:
  
  minwidth  = 'auto' or a numeric value
  maxwidth  = 'auto' or a numeric value
  minheight = 'auto' or a numeric value
  maxheight = 'auto' or a numeric value
  
  It allows to set the window bounds. If set to 'auto', then the
  size is calculated depending of the children size requirement.
  

  - Creates the a window
  - Can have all common attributes.
  - Is a single-element container.
  - If more than one <window> element is present, the 'name' attribute is used to identify them
  - all gui elements can only be placed in here
  
  
  IV. Layout elements
  -------------------
  
  *****************************************************************
  hbox and vbox
  *****************************************************************

    Arrange the elements horizontally or vertically. Can contain
    any number of children.

    Accepted keys in the XML: 
    All common attributes and the following:
  
    spacing   = space to add between the packed childs (default=5)
  
    expand    = yes           - items get bigger to fill all space (default)
                no            - do not expand to fill all space 
                equal         - force equal sized items
                item:<number> - expand only one item if space is available
  
    align     = top/left      - only applied when expand="no", top/left is the default
                center
                bottom/right

  *****************************************************************
  gridbox 
  *****************************************************************
  
    Align elements in a table. Can contain
    any number of children.
    
    Accepted keys in the XML:
    All common attributes and the following:
  
    columns = number of columns (default = 2)
  
    colspacing = space to add between columns/rows (default = 5)
    rowspacing
  
    colexpand = yes           - items get bigger to fill all space
    rowexpand   no            - do not expand to fill all space
                equal         - force equal sized items
                item:<number> - expand only one item if space is available
  
                for colexpand, Default=yes, For rowexpand, Default=no
  
    Any child within a gridbox can have these keys:
  
    colspan = number of columns to span (default = 1)
    rowspan = number of rows to span
  
  *****************************************************************
  multibox
  *****************************************************************
   
    A box with multiple childs in the same position. Used to put multiple containers
    inside and show only one of them at a time. Can contain
    any number of children.
   
    Accepted keys in the XML:

    All common attributes.
    
  *****************************************************************
  singlebox
  *****************************************************************
   
    A box with just one child. Used only to apply extra margin/alignment properties to a child.
    Its called a box (as all virtual containers are called that).

    Accepted keys in the XML:
    
    All common attributes and the following:
  
    margin = margin around the content (default = 10)
             can be a single number (= all margin), or a combination of
             top:<num>,left:<num>,right:<num>,bottom:<num>,vertical:<num>,horizontal:<num>
             example: "vertical:5,left:10,right:0"
  
    expand = yes        - expand child to fill all space (default)
             no         - no expanding
             vertical   - expand vertically only
             horizontal - expand horizontally only
  
    expandwidth  = max size to expand the children to. If the requested size is larger than
    expandheight   this setting then the request size is used (ie the content does not get smaller)
                   default=0
  
    align  = combination of top,left,bottom,right and center. (only effective when expand <> yes)
             example: "top, center" or "top, left" (default) 
             
             
             
  V. Gadget elements
  ------------------

  All common XML attributes are supported. To bind an event procedure directly in the xml, the following attributes
  are available for the gadgets:
  
    onevent      = EventProcedure() - generic event binding, for all event type
    onchange     = EventProcedure() - #PB_EventType_Change binding (only for gadget which support this event type)
    onfocus      = EventProcedure() - #PB_EventType_Focus binding (only for gadget which support this event type)
    onlostfocus  = EventProcedure() - #PB_EventType_LostFocus binding (only for gadget which support this event type)
    ondragstart  = EventProcedure() - #PB_EventType_DragStart binding (only for gadget which support this event type)
    onrightclick = EventProcedure() - #PB_EventType_RightClick binding (only for gadget which support this event type)
    onleftclick  = EventProcedure() - #PB_EventType_LeftClick binding (only for gadget which support this event type)
    onrightdoubleclick = EventProcedure() - #PB_EventType_RightDoubleClick binding (only for gadget which support this event type)
    onleftdoubleclick  = EventProcedure() - #PB_EventType_LeftDoubleClick binding (only for gadget which support this event type)
    
  The 'EventProcedure()' has to be declared as 'Runtime' in the main code, and has to respect the BindEvent() procedure
  format. Under the hood, BindGadgetEvent() is called with the specified procedure.
  
  Supported gadgets:

  <button>
  <buttonimage>
  <calendar>
  <canvas>
  <checkbox>
  <combobox>
  <container> - single element container
  <date>
  <editor>
  <explorercombo>
  <explorerlist>
  <explorertree> 
  <frame> - single element container
  <hyperlink>
  <ipaddress>
  <image>
  <listicon> 
  <listview>
  <option group> - use the same 'group' number to create linked OptionGadget().
  <panel> - can contain <tab> items only
  <progressbar min max value> 
  <scrollarea scrolling="vertical,horizontal or both (default)" innerheight="value or auto (default)" innerwidth="value or auto (default)" step> - single element container, scrolling value determines growth behavior
  <scrollbar min max page value> - page = page length
  <spin min max value>
  <splitter firstmin="value or auto" secondmin> - must contain 2 subitems, so its a 2 item container basically, minimum size is determined by contained gadgets. If "auto" is specified, the min value will be the minimum size of the child.
  <string>
  <text>
  <trackbar min max value>
  <tree>
  <web>
  <scintilla> - callback remains empty

  Gadget related elements:
  <tab> - single element container, for panel tabs (attribute 'text' is supported).
  
  Special elements:
  <empty> - an empty element, useful when it's needed to have space between element, to align them to borders for example. 

Example: Simple resizable dialog

  #Dialog = 0
  #Xml = 0
  
  XML$ = "<window id='#PB_Any' name='test' text='test' minwidth='auto' minheight='auto' flags='#PB_Window_ScreenCentered | #PB_Window_SystemMenu | #PB_Window_SizeGadget'>" +
         "  <panel>" +
         "    <tab text='First tab'>" +
         "      <vbox expand='item:2'>" +
         "        <hbox>" +
         "          <button text='button 1'/>" +
         "          <checkbox text='checkbox 1'/>" +
         "          <button text='button 2'/>" +
         "        </hbox>" +
         "        <editor text='content' height='150'/>" +
         "      </vbox>" +
         "    </tab>" +
         "    <tab text='Second tab'>" +
         "    </tab>" +
         "  </panel>" +
         "</window>"
  
  If ParseXML(#Xml, XML$) And XMLStatus(#Xml) = #PB_XML_Success
    
    If CreateDialog(#Dialog) And OpenXMLDialog(#Dialog, #Xml, "test")
      
      Repeat
        Event = WaitWindowEvent()
      Until Event = #PB_Event_CloseWindow 
      
    Else  
      Debug "Dialog error: " + DialogError(#Dialog)
    EndIf
  Else
    Debug "XML error: " + XMLError(#Xml) + " (Line: " + XMLErrorLine(#Xml) + ")"
  EndIf

Example: Multibox example

    #Dialog = 0
  #Xml = 0
  
  Runtime Enumeration Gadget
    #ListView
    #GeneralContainer
    #EditorContainer
    #BackupContainer
  EndEnumeration
  
  Procedure ShowPanels()
    
    HideGadget(#GeneralContainer, #True)
    HideGadget(#EditorContainer, #True) 
    HideGadget(#BackupContainer, #True)
    
    Select GetGadgetState(#ListView)
      Case 0
        HideGadget(#GeneralContainer, #False)
        
      Case 1
        HideGadget(#EditorContainer, #False)
        
      Case 2
        HideGadget(#BackupContainer, #False)
    EndSelect
  EndProcedure
  
  Runtime Procedure OnListViewEvent()
    ShowPanels()
  EndProcedure
  
  XML$ = "<window id='#PB_Any' name='test' text='Preferences' minwidth='auto' minheight='auto' flags='#PB_Window_ScreenCentered | #PB_Window_SystemMenu | #PB_Window_SizeGadget'>" +
         "  <hbox expand='item:2'>" +
         "    <listview id='#ListView' width='100' onEvent='OnListViewEvent()'/>" +
         "    <multibox>" +
         "" +
         "      <container id='#GeneralContainer' invisible='yes'>" +
         "        <frame text='General'>" +
         "          <vbox expand='no'>" +
         "            <checkbox text='Enable red light'/>" +
         "            <checkbox text='Enable green light'/>" +
         "          </vbox>" +
         "        </frame>" +
         "      </container>" +
         "" +
         "      <container id='#EditorContainer' invisible='yes'>" +
         "        <frame text='Editor'>" +
         "          <vbox expand='no'>" +
         "            <checkbox text='Set read only mode'/>" +
         "            <checkbox text='Duplicate line automatically'/>" +
         "            <checkbox text='Enable monospace font'/>" +
         "          </vbox>" +
         "        </frame>" +
         "      </container>" +
         "" +
         "      <container  id='#BackupContainer' invisible='yes'>" +
         "      <frame text='Backup'>" +
         "        <vbox expand='no'>" +
         "          <checkbox text='Activate backup'/>" +
         "        </vbox>" +
         "      </frame>" +
         "      </container>" +
         "" +
         "    </multibox>" +
         "  </hbox>" +
         "</window>"
  
  If ParseXML(#Xml, XML$) And XMLStatus(#Xml) = #PB_XML_Success
    
    If CreateDialog(#Dialog) And OpenXMLDialog(#Dialog, #Xml, "test")
      
      AddGadgetItem(#ListView, -1, "General")
      AddGadgetItem(#ListView, -1, "Editor")
      AddGadgetItem(#ListView, -1, "Backup")
      
      SetGadgetState(#ListView, 0)
      
      ShowPanels()
      
      Repeat
        Event = WaitWindowEvent()
      Until Event = #PB_Event_CloseWindow 
      
    Else  
      Debug "Dialog error: " + DialogError(#Dialog)
    EndIf
  Else
    Debug "XML error: " + XMLError(#Xml) + " (Line: " + XMLErrorLine(#Xml) + ")"
  EndIf

Example: Gridbox example

  #Dialog = 0
  #Xml = 0
  
  XML$ = "<window id='#PB_Any' name='test' text='Gridbox' minwidth='auto' minheight='auto' flags='#PB_Window_ScreenCentered | #PB_Window_SystemMenu | #PB_Window_SizeGadget'>" +
         "    <gridbox columns='6'>" +
         "          <button text='Button 1' />" +
         "          <button text='Button 2' />" +
         "          <button text='Button 3' colspan='3' />" +
         "          <button text='Button 4' />" +
         "          <button text='Button 5' rowspan='2' />" +
         "          <button text='Button 6' />" +
         "          <button text='Button 7' />" +
         "          <button text='Button 8' />" +
         "          <button text='Button 9' />" +
         "          <button text='Button 10' />" +
         "          <button text='Button 11' />" +
         "          <button text='Button 12' />" +
         "    </gridbox>" +
         "  </window>"
  
  If ParseXML(#Xml, XML$) And XMLStatus(#Xml) = #PB_XML_Success
    
    If CreateDialog(#Dialog) And OpenXMLDialog(#Dialog, #Xml, "test")
      
      Repeat
        Event = WaitWindowEvent()
      Until Event = #PB_Event_CloseWindow 
      
    Else  
      Debug "Dialog error: " + DialogError(#Dialog)
    EndIf
  Else
    Debug "XML error: " + XMLError(#Xml) + " (Line: " + XMLErrorLine(#Xml) + ")"
  EndIf

See Also

CreateDialog()

Supported OS

All

<- IsDialog() - Dialog Index - RefreshDialog() ->