PageWindow
The PageWindow provides an automated display for creating a book-like layout.
| PageWindow | The PageWindow provides an automated display for creating a book-like layout. |
| Implementation Details | The PageWindow is a specialized window element that automatically separates a long vertical organization of windows (like you would create for a ScrollWindow out into page-sized sections. |
| XML Definition | This is the PageWindow xml definition. |
| XML Tag | |
| Required Attributes | You need to specify valid values for all of these elements to get the PageWindow to create properly. |
| pagesdisplayed | The number of pages to display. |
| guttersize | The gutter distance between each page. |
| childcontentswindow | Name of the child Window that contains all of the windows to be parsed into pages. |
| Optional Attributes | These attributes are optional. |
| pagenumbertemplate | Name of a valid Label defintion to use for the page numbers. |
| Functions | |
| Functions | |
| PageWindowGetNumPagesDisplayed() | Returns the number of pages that this page window will display at once. |
| Functions | |
| Functions | |
| PageWindowGetNumPages() | Returns the number of pages currently parsed from the childcontentswindow. |
| PageWindowSetCurrentPage() | Sets the left most page on the display. |
| PageWindowGetCurrentPage() | Returns the index of the current left-most page. |
| PageWindowUpdatePages() | Processes all of the child windows to update the page layout. |
| PageWindowClearPageBreaks() | Clears out all registered Page-Break windows. |
| PageWindowAddPageBreak() | Adds a new Page-Break window. |
| PageWindowRemovePageBreak() | Removes the Page-Break for a specific window. |
| PageWindowClearSplitableWindows() | Clears out all registered Splitable windows. |
| PageWindowAddSplitableWindow() | Adds a new Splittable window. |
| PageWindowRemoveSplitableWindow() | Removes the splittable flag for a specific window. |
Implementation Details
The PageWindow is a specialized window element that automatically separates a long vertical organization of windows (like you would create for a ScrollWindow out into page-sized sections.
Each page is parsed out by determing which child-window elements will fit entirely on that page. Anything hanging off the bottom will be pushed to the top of the next page. You can also designated specific window elements as ‘page breaks’, so that they will always begin at the top of a page.
There are two exceptions to this logic.
When a Label hangs off the edge of the page, will split the text a cross multiple pages as needed to produce a book-like layout.
If you explictly specify a window as ‘splitable’ by calling PageWindowAddSplitableWindow(), the definition that window will be duplicated so it is shown across all pages. NOTE Currently this only cause the window definition to be duplicated, and only the size and position information a transfered to the new window. This is not a true clone.
Creation
To create a PageDisplay, you can specify the follow general settings.
- The number of pages to display at a time. (1 to n )
- The guttersize between the pages.
- An optional Label defintion for the page numbers.
The width of each page is dermined from the number of pages displayed, the gutter size, and the window width.
pageWidth = windowWidth / ( pagesDisplayed - gutterSize*(pagesDisplayed-1) )
XML Definition
This is the PageWindow xml definition.
| XML Tag | |
| Required Attributes | You need to specify valid values for all of these elements to get the PageWindow to create properly. |
| pagesdisplayed | The number of pages to display. |
| guttersize | The gutter distance between each page. |
| childcontentswindow | Name of the child Window that contains all of the windows to be parsed into pages. |
| Optional Attributes | These attributes are optional. |
| pagenumbertemplate | Name of a valid Label defintion to use for the page numbers. |
Required Attributes
You need to specify valid values for all of these elements to get the PageWindow to create properly.
Functions
| Functions | |
| PageWindowGetNumPagesDisplayed() | Returns the number of pages that this page window will display at once. |
PageWindowGetNumPagesDisplayed()
Returns the number of pages that this page window will display at once.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
Returns
| numPagesDisplayed | (number) The number of pages displayed at once. |
Notes
- none
Example
local numPagesDisplayed = PageWindowGetNumPagesDisplayed( pageWindow )
Functions
| Functions | |
| PageWindowGetNumPages() | Returns the number of pages currently parsed from the childcontentswindow. |
| PageWindowSetCurrentPage() | Sets the left most page on the display. |
| PageWindowGetCurrentPage() | Returns the index of the current left-most page. |
| PageWindowUpdatePages() | Processes all of the child windows to update the page layout. |
| PageWindowClearPageBreaks() | Clears out all registered Page-Break windows. |
| PageWindowAddPageBreak() | Adds a new Page-Break window. |
| PageWindowRemovePageBreak() | Removes the Page-Break for a specific window. |
| PageWindowClearSplitableWindows() | Clears out all registered Splitable windows. |
| PageWindowAddSplitableWindow() | Adds a new Splittable window. |
| PageWindowRemoveSplitableWindow() | Removes the splittable flag for a specific window. |
PageWindowGetNumPages()
Returns the number of pages currently parsed from the childcontentswindow.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
Returns
| numPages | (number) The number of pages currently in the display. |
Notes
- none
Example
local numPages = PageWindowGetNumPages( pageWindow )
PageWindowSetCurrentPage()
Sets the left most page on the display.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
| curPage | (number) The index number for the left most page. |
Returns
| nil | no return value. |
Notes
- The ‘Current Page’ is the left most page shown on the screen. For PageWindows with more than one page visible, ‘current page’ values outside of numPages are allowed to position the first and last pages on any one of the display pages.
Example
PageWindowSetCurrentPage( "SomePageWindow", 1 )
PageWindowGetCurrentPage()
Returns the index of the current left-most page.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
Returns
| curPage | (number) The index number for the left most page. |
Notes
- none
Example
local curPage = PageWindowGetCurrentPage( "SomePageWindow" )
PageWindowUpdatePages()
Processes all of the child windows to update the page layout.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
Returns
| nil | no return value. |
Notes
- This should be called any time the PageWindow contents changes in a way that might affect its layout.
Example
PageWindowUpdatePages( "SomePageWindow" )
PageWindowClearPageBreaks()
Clears out all registered Page-Break windows.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
Returns
| nil | no return value. |
Notes
- none
Example
PageWindowClearPageBreaks( "SomePageWindow" )
PageWindowAddPageBreak()
Adds a new Page-Break window. This window will always be displayed at the top of a page.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
| pageBreakWindowName | (string) The name of a child window of the childcontentswindow. |
Returns
| nil | no return value. |
Notes
- You must manually call <PageBreakUpdatePages()> to see the layout change.
Example
PageWindowAddPageBreak( "SomePageWindow", "ChapterTwoHeading" )
PageWindowRemovePageBreak()
Removes the Page-Break for a specific window.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
| pageBreakWindowName | (string) The name of a child window of the childcontentswindow. |
Returns
| nil | no return value. |
Notes
- You must manually call <PageBreakUpdatePages()> to see the layout change.
Example
PageWindowRemovePageBreak( "SomePageWindow", "ChapterTwoHeading" )
PageWindowClearSplitableWindows()
Clears out all registered Splitable windows.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
Returns
| nil | no return value. |
Notes
- none
Example
PageWindowClearSplitableWindows( "SomePageWindow" )
PageWindowAddSplitableWindow()
Adds a new Splittable window. When this window overhangs the page, it will duplicated so that it split between the pages rather than pushed to the next page.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
| spilableWindowName | (string) The name of a child window of the childcontentswindow. |
Returns
| nil | no return value. |
Notes
- You must manually call PageWindowUpdatePages() to see the layout change.
Example
PageWindowAddSplitableWindow( "SomePageWindow", "SomeTextBorder" )
PageWindowRemoveSplitableWindow()
Removes the splittable flag for a specific window.
Parameters
| pageWindowName | (string) The name of the PageWindow. |
| splitableWindowName | (string) The name of a child window of the childcontentswindow. |
Returns
| nil | no return value. |
Notes
- You must manually call PageWindowUpdatePages() to see the layout change.
Example
PageWindowRemoveSplitableWindow( "SomePageWindow", "SomeTextBorder" )