Novalys, your PowerBuilder Specialist


Dockable Windows

In PowerBuilder Classic, you can set docking behaviors for the sheets that open in the MDI (multiple document interface) frame window.

In this section:

Window Types and Docking States

New window types allow sheets to open in one of four states: docked, floating, tabbed document, or tabbed window.

The two new WindowType values are mdidock! and mdidockhelp!. Like mdi! and mdihelp!, you can open sheets (child windows) with the new OpenSheet functions.

Docked
The sheet is open and fixed in position relative to the Window object. The docked state is the default.
Floating
Users can move a floating sheet around or even outside the Window object.
TabbedDocument
Sheets that appear tabbed in the same area of the Window.
TabbedWindow
Docked windows that occupy the same area of the Window are in a tabbed group. The tabs are at the bottom.

You can get each opened sheet's status using the enumerated type WindowDockState.

  • WindowDockStateDocked!
  • WindowDockStateFloating!
  • WindowDockStateTabbedDocument!
  • WindowDockStateTabbedWindow!

Open Sheets in a Specific State

New versions of the OpenSheet function allow you to open a sheet at a specific docking location, in a specific tab group, or as a document.
You can programmatically open sheets in a specific state using these new PowerScript® functions:

  • OpenSheetAsDocument
  • OpenSheetDocked
  • OpenSheetInTabGroup
  • OpenSheetWithParmAsDocument
  • OpenSheetWithParmDocked
  • OpenSheetWithParmInTabGroup

Opens a sheet as a document within an MDI frame window for dockable windows.

Applies to

Windows objects

Syntax

OpenSheetAsDocument ( <sheetrefvar> {, <windowtype> }, <mdiframe>, <sheetname> {, <tabalign> } )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetAsDocument places a reference to the open sheet in <sheetrefvar>.
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<mdiframe> The name of an MDI frame window.
<sheetname> A unique string identifier for the sheet, which is used when layout is persisted.
<tabalign> (optional) A boolean that, when used, creates a new tab group and indicates the alignment of the sheets in the group. When true, the tabs in the group align vertically. When false, the tabs align horizontally.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheetAsDocument returns null. In some cases, such as if the <windowtype> argument is invalid, OpenSheetAsDocument throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block.

Usage

Tabbed documents can be in more than one tab group. Users can create additional tab groups by dragging one tab outside of the current group. If there is more than one tab group, use the <mdiframe> argument to specify in which one to open a sheet. Instead of specifying the parent window, specify an already open sheet in the tab group where you want to open your new sheet.

Opens a sheet as a document within an MDI frame window for dockable windows. OpenSheetWithParmAsDocument also stores a parameter in the system's Message object so that it is accessible to the opened sheet.

Applies to

Windows objects

Syntax

OpenSheetWithParmAsDocument ( <sheetrefvar>, <parameter> {, <windowtype> }, <mdiframe>, <sheetname> {, <tabalign> } )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetWithParmAsDocument places a reference to the open sheet in <sheetrefvar>.
<parameter> The parameter you want to store in the Message object when the sheet is opened. <Parameter> must have one of these datatypes:
  • String
  • Double
  • PowerObject
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<mdiframe> The name of an MDI frame window.
<sheetname> A unique string identifier for the sheet, which is used when layout is persisted.
<tabalign> (optional) A boolean that, when used, creates a new tab group and indicates the alignment of the sheets in the group. When true, the tabs in the group align vertically. When false, the tabs align horizontally.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null,OpenSheetWithParmAsDocument returns null. In some cases, such as if the <windowtype> argument is invalid,OpenSheetWithParmAsDocument throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block.

Usage

Tabbed documents can be in more than one tab group. Users can create additional tab groups by dragging one tab outside of the current group. If there is more than one tab group, use the <mdiframe> argument to specify in which one to open a sheet. Instead of specifying the parent window, specify an already open sheet in the tab group where you want to open your new sheet.

The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenSheetWithParmAsDocument, scripts for the opened sheet would check one of the following properties.

Message object property Argument datatype
Message.DoubleParm Double
Message.PowerObjectParm PowerObject (PowerBuilder objects, including user-defined structures)
Message.StringParm String

In the opened window, it is a good idea to access the value passed in the Message object immediately (because some other script may use the Message object for another purpose).

NoteWhen you pass a PowerObject as a parameter, you are passing a reference to the object. The object must exist when you refer to it later or you get a null object reference, which causes an error. For example, if you pass the name of a control on a window that is being closed, that control will not exist when a script accesses the parameter.

Opens a sheet docked in a specified position within an MDI frame window for dockable windows. OpenSheetWithParmDocked also stores a parameter in the system's Message object so that it is accessible to the opened sheet.

Applies to

Windows objects

Syntax

OpenSheetWithParmDocked ( <sheetrefvar>, <parameter> {, <windowtype> }, <mdiframe>, <position>, <sheetname> )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetWithParmDocked places a reference to the open sheet in <sheetrefvar>.
<parameter> The parameter you want to store in the Message object when the sheet is opened. <Parameter> must have one of these datatypes:
  • String
  • Double
  • PowerObject
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<mdiframe> The name of an MDI frame window.
<position> An enumerated type that specifies where to dock the sheet:
  • WindowDockLeft!
  • WindowDockRight!
  • WindowDockTop!
  • WindowDockBottom!
<sheetname> A unique string identifier for the sheet, which is used when layout is persisted.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheetWithParmDocked returns null. In some cases, such as if the <windowtype> argument is invalid, OpenSheetWithParmDocked throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block.

Usage

The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenSheetWithParmFromDocked, scripts for the opened sheet would check one of the following properties.

Message object property Argument datatype
Message.DoubleParm Double
Message.PowerObjectParm PowerObject (PowerBuilder objects, including user-defined structures)
Message.StringParm String

In the opened window, it is a good idea to access the value passed in the Message object immediately (because some other script may use the Message object for another purpose).

Note

When you pass a PowerObject as a parameter, you are passing a reference to the object. The object must exist when you refer to it later or you get a null object reference, which causes an error. For example, if you pass the name of a control on a window that is being closed, that control will not exist when a script accesses the parameter.

Opens a sheet in a tab group within an MDI frame window for dockable windows.

Applies to

Windows objects

Syntax

OpenSheetInTabGroup ( <sheetrefvar> {, <windowtype> }, <siblingname>, <sheetname> )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetInTabGroup places a reference to the open sheet in <sheetrefvar>.
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<siblingname> The name of a sibling window in either a docked state or in a non-document tab group. The sheet opens in that tab group.
<sheetname> A unique string identifier for the sheet, which is used when layout is persisted.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheetInTabGroup returns null. In some cases, such as if the <windowtype> argument is invalid, OpenSheetInTabGroup throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block.

Usage

The first sheet opened in a main window cannot be opened using OpenSheetInTabGroup or OpenSheetWithParmInTabGroup. To create a tab group, open the first sheet as a docked sheet and then use that sheet as the <siblingname> argument.

Opens a sheet in a tab group within an MDI frame window for dockable windows. OpenSheetWithParmInTabGroup also stores a parameter in the system's Message object so that it is accessible to the opened sheet.

Applies to

Windows objects

Syntax

OpenSheetWithParmInTabGroup ( <sheetrefvar>, <parameter> {, <windowtype> }, <siblingname>, <sheetname> )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetWithParmInTabGroup places a reference to the open sheet in <sheetrefvar>.
<parameter> The parameter you want to store in the Message object when the sheet is opened. <Parameter> must have one of these datatypes:
  • String
  • Double
  • PowerObject
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<siblingname> The name of a sibling window in either a docked state or in a non-document tab group. The sheet opens in that tab group.
<sheetname> A unique string identifier for the sheet, which is used when layout is persisted.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheetWithParmInTabGroup returns null. In some cases, such as if the <windowtype> argument is invalid, OpenSheetWithParmInTabGroup throws a runtime error and does not return a value; therefore, it is recommended that you both test the return value and wrap the function call in a try-catch block.

Usage

The first sheet opened in a main window cannot be opened using OpenSheetInTabGroup or OpenSheetWithParmInTabGroup. To create a tab group, open the first sheet as a docked sheet and then use that sheet as the <siblingname> argument. The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenSheetWithParmFromDockingState, scripts for the opened sheet would check one of the following properties.

Message object property Argument datatype
Message.DoubleParm Double
Message.PowerObjectParm PowerObject (PowerBuilder objects, including user-defined structures)
Message.StringParm String

In the opened window, it is a good idea to access the value passed in the Message object immediately (because some other script may use the Message object for another purpose).

Note

When you pass a PowerObject as a parameter, you are passing a reference to the object. The object must exist when you refer to it later or you get a null object reference, which causes an error. For example, if you pass the name of a control on a window that is being closed, that control will not exist when a script accesses the parameter.

 

Sample code for opening docked windows and tabbed documents.

Procedure

Windows objects

  1. Create a window w_sheet_any as a main! window type.
  2. In the open event of w_sheet_any, add this code:
    string ls_i  
    ls_i = Message.stringparm  
    if not isnull(ls_i) and ls_i <> "" then
          this.title = ls_i  
    end if
  3. Create an MDIDock window w_mdidock_dockstate and set any menu in it.
  4. In the open event of w_mdidock_dockstate, add this code:
    window win[]  
    OpenSheetWithParmDocked(win[1], "1", "w_sheet_any", this, WindowDockLeft!, "") OpenSheetWithParmInTabGroup(win[2], "2", "w_sheet_any", this, "") OpensheetWithParmInTabGroup(win[3], "3", "w_sheet_any", win[1], "") OpenSheetWithParmAsDocument(win[4], "4", "w_sheet_any", this, "") OpenSheetWithParmAsDocument(win[5], "5", "w_sheet_any", win[4], "") OpenSheetWithParmAsDocument(win[6], "6", "w_sheet_any", this, "", false) OpenSheetWithParmAsDocument(win[7], "7", "w_sheet_any", win[5], "") OpenSheetWithParmAsDocument(win[8], "8", "w_sheet_any", win[6], "")
  5. Run the application
    You will see windows 1 and 3 as a tabbed group, with the tabs at the bottom. Sheets 4, 5, and 7 appear as tabbed documents together, as do 6 and 8, both groups with tabs at the top. Window 2 is alone and untabbed.

Persist the MDI State

You can set the application so that, when the user launches the application, the sheets are open in the same position and state as when the user closed it.

To persist the states of opened sheets, it is important to associate a meaningful string ID with each opened sheet. There are two ways to do this:

  • Set it as an argument when using the OpenSheetAsDocument, OpenSheetWithParmAsDocument,OpenSheetDocked, OpenSheetWithParmDocked, OpenSheetInTabGroup, orOpenSheetWithParmInTabGroup function.
  • Set it using the SetSheetID function.

You can use a function to store the MDI state in the registry when the application closes. You can then use other functions to load and open the sheets in their docking states, and present them.

Sets the unique identifier for an open sheet.

Applies to

Window objects

Syntax

<controlname>.SetSheetID ( <sheetname> )
Argument Description
<controlname> The open sheet to be identified.
<sheetname> A unique string identifier for the sheet, which is used when layout is persisted.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, SetSheetID returns null.

Usage

If no sheet indentifier was set when it was opened by one of the OpenSheet functions, you can set an ID using theSetSheetID function. You can also change a sheet's ID.

Example

window win[]  OpenSheetDocked(win[1], this, WindowDockLeft!, "")  win[1].SetSheetID("sheet1")

 

Stores the MDI state in the registry.

Applies to

Window objects

Syntax

SaveDockingState ( <regkey> )
Argument Description
<regkey> The <regkey> argument is the registry key. If no entry for the key exists in the registry, one is created. Existing keys are overwritten.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, SaveDockingStatereturns null.

Usage

You can set the application so that it saves the states of the open sheets. You should call this function when the application closes.

Example

Save all sheets in register
integer li_rtn  string is_register = "Sybase\PowerBuilder\Examples\Docking\"  li_rtn = this.SaveDockingState (is_register)

 

Loads two arrays of equal size: type names of persisted sheets and the corresponding IDs.

Applies to

Window objects

Syntax

LoadDockingState ( <regkey>, <windowtypes>, <sheetnames> )
Argument Description
<regkey> The registry key where the information was stored using theSaveDockingState function.
<windowtypes> A string array of window types for all the child windows that were persisted.
<sheetnames> A string array of the unique IDs for the persisted child windows corresponding to the types in the <windowtypes>array.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, LoadDockingStatereturns null.

Usage

To retrieve the MDI states that were saved using the SaveDockingState function, use LoadDockingState to get the window information from the registry. Next, use OpenSheetFromDockingState orOpenSheetWithParmFromDockingState to open each of the persisted sheets. Finally, use CommitDocking to do the final arrangement and make the sheets visible.

Opens one or more persisted sheets within an MDI frame window for dockable windows.

Applies to

Windows objects

Syntax

OpenSheetFromDockingState ( <sheetrefvar> {, <windowtype> }, <mdiframe>, <sheetname> )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetFromDockingState places a reference to the open sheet in <sheetrefvar>.
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<mdiframe> The name of an MDI frame window.
<sheetname> The unique string identifier for the sheet.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null, OpenSheetFromDockingState returns null.

Usage

Open persisted sheets in their saved docking states.

Opens one or more persisted sheets within an MDI frame window for dockable windows.OpenSheetWithParmFromDockingState also stores a parameter in the system's Message object so that it is accessible to the opened sheet.

Applies to

Windows objects

Syntax

OpenSheetWithParmFromDockingState ( <sheetrefvar>, <parameter> {, <windowtype> }, <mdiframe>, <sheetname> )
Argument Description
<sheetrefvar> The name of any window variable that is not an MDI frame window. OpenSheetWithParmFromDockingState places a reference to the open sheet in <sheetrefvar>.
<parameter> The parameter you want to store in the Message object when the sheet is opened. <Parameter> must have one of these datatypes:
  • String
  • Double
  • PowerObject
<windowtype> (optional) A string whose value is the datatype of the window you want to open. The datatype of <windowtype> must be the same or a descendant of <sheetrefvar>.
<mdiframe> The name of an MDI frame window.
<sheetname> The unique string identifier for the sheet.

Returns

Integer. Returns 1 if it succeeds and -1 if an error occurs. If any argument's value is null,OpenSheetWithParmFromDockingState returns null.

Usage

The system Message object has three properties for storing data. Depending on the datatype of the parameter specified for OpenSheetWithParmFromDockingState, scripts for the opened sheet would check one of the following properties.

Message object property Argument datatype
Message.DoubleParm Double
Message.PowerObjectParm PowerObject (PowerBuilder objects, including user-defined structures)
Message.StringParm String

In the opened window, it is a good idea to access the value passed in the Message object immediately (because some other script may use the Message object for another purpose).

Note

When you pass a PowerObject as a parameter, you are passing a reference to the object. The object must exist when you refer to it later or you get a null object reference, which causes an error. For example, if you pass the name of a control on a window that is being closed, that control will not exist when a script accesses the parameter.

After all persisted sheets are opened, this function arranges them and makes them visible.

Applies To

Window objects

Syntax

CommitDocking()

Usage

When all persisted sheets are opened using the LoadDockingState and OpenSheetFromDockingState orOpenSheetWithParmFromDockingState, the CommitDocking function does the work of arranging everything in place and making it all visible.

Example

Restore all sheets for register

string s1[], s2[]  
string is_register = "Sybase\PowerBuilder\Examples\Docking\"  
integer li_start, li_end, li_i, li_rtn  
li_rtn = LoadDockingState(is_register,s1,s2)  
window lw_window  li_start = lowerbound(s1)  
li_end = upperbound(s2)
    
for li_i = li_start to li_end
  	openSheetFromDockingState(lw_window,s1[li_i], this, s2[li_i])  
next  
CommitDocking()

Properties for Dockable Windows

Customize the behavior and appearance of the windows and tabs.

These properties are similar to existing properties for

Options for Child Windows

WindowDockOptions are for child windows to specify how they can be opened:

  • WindowDockOptionAll!
  • WindowDockOptionTabbedDocumentOnly!
  • WindowDockOptionDockedOnly!
  • WindowDockOptionFloatOnly!
  • WindowDockOptionTabbedDocumentAndDockedOnly!
  • WindowDockOptionTabbedDocumentAndFloatOnly!
  • WindowDockOptionDockedAndFloatOnly!

Tabs

Properties for the shapes of the tabs:

  • windowdocktabslanted!
  • windowdocktabrectangular!
  • windowdocktabsingleslanted!

Location of the close button on a tab, if any:

  • windowdocktabclosebuttonnone!
  • windowdocktabclosebuttononactive!
  • windowdocktabclosebuttonshared!

Colors of tabs:

  • gradients are available
  • default to theme colors is available

Icon and Scroll Button for tabbed windows or documents:

  • TabbedWindowTabIcon / TabbedDocumentTabIcon
  • TabbedWindowTabScroll / TabbedDocumentTabScroll

Tabbed Window and Document Title Bars

Colors of tabbed window and document title bars:

  • TabbedWindowActiveTabBackColor / TabbedDocumentActiveTabBackColor
  • TabbedWindowActiveTabGradientBackColor / TabbedDocumentActiveTabGradientBackColor
  • TabbedWindowActiveTabTextColor / TabbedDocumentActiveTabTextColor
  • TabbedWindowInActiveTabBackColor / TabbedDocumentInActiveTabBackColor
  • TabbedWindowInActiveTabGradientBackColor / TabbedDocumentInActiveTabGradientBackColor
  • TabbedWindowInActiveTabTextColor / TabbedDocumentInActiveTabTextColor
  • TabbedWindowMouseoverTabBackColor / TabbedDocumentMouseoverTabBackColor
  • TabbedWindowMouseoverTabGradientBackColor / TabbedDocumentMouseoverTabGradientBackColor
  • TabbedWindowMouseoverTabTextColor / TabbedDocumentMouseoverTabTextColor
  • TabbedWindowTabsAreaColor / TabbedDocumentTabsAreaColor
  • TabbedWindowTabsAreaGradientColor / TabbedDocumentTabsAreaGradientColor
  • TabbedWindowTabsAreaGradientVert / TabbedDocumentTabsAreaGradientVert

Title bar states:

  • TitleBarActiveColor / TitleBarInActiveColor
  • TitleBarActiveGradientColor / TitleBarInActiveGradientColor
  • TitleBarActiveGradientVert / TitleBarInActiveGradientVert
  • TitleBarActiveaTextColor / TitleBarInActiveTextColor