WinNewPinAt

Allows for windows to be "pinned" at specified locations within a main window or within other pinned windows. This function opens a new display window at a specified location, relative to the current active window, with a selected page displayed. The window can later be removed with the WinFree() function.

The pinned windows become child windows of the parent window, and maintain their size and position relative to the parent window.

Pinned windows do not have a border, title bar or title. They cannot be maximized or minimized. Pinned windows are automatically closed when the main window is closed. They can be created in one of the following modes (as detailed in the Syntax section below).

• As the window is sized, the page inside maintains its original aspect ratio. The aspect ratio defines the relationship between the width and the height of the window. In this mode, the page is aligned to the top left. Blank areas are filled in using the background color of the main window.

• As the window is sized, the page inside maintains its original size. Scroll bars are displayed to allow the user to navigate the window if the content cannot be accommodated in the window. The scroll bars can be disabled using the Cicode function WinStyle OR by passing in various modes into the winnewpinat mode parameter.

• the page is stretched to fit in the window. For example, consider a page that is resized to three times the original width, and half the original height. If this mode is set, the font size of the text on the page will be tripled (in proportion with the maximum scale).

  

  Note: Pinned windows cannot overlap. If you use this function to create a pinned window that overlaps an existing one, the window will not appear and the "Pinned window overlaps" hardware alarm will be generated.

The content of pinned windows can be manipulated using most Windows Cicode functions except the following:

• GetWinTitle()

• WinMode()

• WinTitle()

• WndShow()

  Note: This function is not supported in the server process in a multiprocessor environment. Calling this function from the server process results in a hardware alarm being raised.

You can also specify if the displayed page operates within the context of a particular cluster in a multiple cluster project. When the page is displayed during runtime, the ClusterName argument is used to resolve any tags that have a cluster omitted.

Note: When executing a keyboard command while the focus is in a pinned window, the keyboard command will first be matched against the list of keyboard commands associated with the graphics object that has current focus, and then the list of keyboard commands associated with the pinned window page itself. The keyboard command will then be matched against the list of keyboard commands associated with the parent of the pinned window, and so on. Command execution will stop at the first object or page that matches the keyboard command sequence.

Syntax

WinNewPinAt(Page, X, Y[, Mode][, Width][, Height][, sClusterName])

Page:

The name or page number of the page to display (in quotation marks ""). Can be prefixed by the name of a host cluster, that is "ClusterName.Page". This will take precedence over the use of the ClusterName parameter if the two differ.

X:

The x pixel coordinate of the top left corner of the window.

Y:

The y pixel coordinate of the top left corner of the window.

Mode:

The mode of the window:

0 - Set by default. Normal page, maintain aspect ratio when resized. The aspect ratio defines the relationship between the width and the height of the window.

1024 - Disables dynamic resizing of the new window.

4096 - Allows the window to be resized without maintaining the current aspect ratio. The aspect ratio defines the relationship between the width and the height of the window, which means this setting allows you to stretch or compress the window to any proportions.

8192 - Text on a page will be resized in proportion with the maximum scale change for a resized window. This option overrides the setting of the [Page]ScaleTextToMax parameter.

You can select multiple modes by adding modes together.

Width:

The pixel width of the window, scaled relative to the current active window.

Default value - The width of the page associated with argument 'Page'.

Height:

The pixel height of the window, scaled relative to the current active window.

Default value - The height of the page associated with argument 'Page'.

sClusterName:

The name of the cluster that will accommodate the page at runtime. This is optional if you have one cluster or are resolving the page via the current cluster context. The argument is enclosed in quotation marks "". If the Page parameter is prefixed with the name of a cluster, this parameter will not be used.

Return Value

The window number of the window, or -1 if the window cannot be opened. Be aware that this is not the same as the window handle returned from the WndFind() function.

Note: A common cause of the window not being created is because you have reached the maximum allowable windows, which can be changed via the parameter [Page]Windows. Also, a window will not be created if it overlaps with an existing one. Check for the "Pinned window overlaps" hardware alarm.

Related Functions

WinFree, WinNew, WinNewAt

Example

Here is a Cicode example that creates three pinned windows using the current window as the parent:

• window 1 : coordinates - 0,0, size - 100, 100, resize mode - maintain aspect ratio

• window 2 : coordinates - 100,0, size - 100, 100, resize mode - stretch content to fit window bounds

• window 3 : coordinates - 0,100, size - 200, 100, resize mode - maintain content size

  INT windowPin1 = -1;

  INT windowPin2 = -1;

  INT windowPin3 = -1;

  INT windowParent = -1;

  FUNCTION MyPinnedLayout()

  IF windowParent = -1 THEN

  windowParent = WinNumber();

  END

  IF windowParent <> -1 THEN

  WinGoto(windowParent);

  windowPin1 = WinNewPinAt("page1", 0, 0, 0, 100, 100);

  IF -1 = windowPin1 THEN

  Prompt("WinNewPinAt failed with error: " + ErrMsg(IsError()));

  END

  WinGoto(windowParent);

  windowPin2 = WinNewPinAt("page2", 100, 0, 4096, 100, 100);

  IF -1 = windowPin2 THEN

  Prompt("WinNewPinAt failed with error: " + ErrMsg(IsError()));

  END

  WinGoto(windowParent);

  windowPin3 = WinNewPinAt("page3", 0, 100, 1024, 200, 100);

  IF -1 = windowPin3 THEN

  Prompt("WinNewPinAt failed with error: " + ErrMsg(IsError()));

  END

  WinGoto(windowParent);

  END

  END

See Also

Window Functions