frame (roll option): Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
m (Initial copyover of dialog content, still needs to be fact checked and cleaned of dialog references. Rewrite recommended for both this and dialog, to remove overly technical jargon and tone.)
 
m (Text replacement - "<source" to "<syntaxhighlight")
 
(24 intermediate revisions by 9 users not shown)
Line 1: Line 1:
{{stub|Cleaned up and all dialog references scrubbed.}}
{{RollOption
{{RollOption
|name=frame
|name=frame
|description=Opens a frame window.  This window can be named; attempts to open another frame with the same name cause the old contents to be removed and new contents displayed.  The initial size of the frame can be specified as well, but once the named frame is opened and resized by the user, that size becomes its default opening size in the future.
|description=
Opens a frame window supporting HTML3.2.  Unlike the modal {{roll|dialog}}, frames are dockable panels that are usually intended to remain open.  Frames can be closed with a button located in the title bar or via the [[closeFrame|closeFrame()]] macro function.


Frames are dockable panels, unlike the modeless {{roll|dialog}}. Frames only have a single button for dismissing the frame, located in the title bar.
|usage=
<syntaxhighlight lang="mtmacro" line>
[h: frame(frameName [,"width; height; temporary; title; tabtitle; scrollreset; value;"] )]
</syntaxhighlight>
 
The first parameter, shown as '''frameName''', should be a double-quoted string that specifies the internal name of the frame window.  The visible title that appears in the title bar of the window is set separately, either by using HTML that appears inside the frame itself or use of the '''title''' parameter from b50 forward.  Any attempts to open another frame with the same name instead cause the old contents to be removed and new contents displayed. Note this behavior relates to the internal name of the frame, not the displayed title of the frame as multiple frames can share a title.  Once the named frame is opened and resized by the user, that size becomes its default opening size in the future, unless the temporary option is set to "1".


|usage=
<source lang="mtmacro" line>
[h: frame(frameName [,"size; input; temporary; title; noframe"] )]
</source>


The first parameter, shown as '''frameName''', should be a double-quoted string that specifies the internal name of the frame window.  (Note that the title that appears in the title bar of the window is set separately, using HTML that appears inside the frame itself.) (use '''title''' parameter from b50 forward)
The second parameter is optional, it is a semicolon separated [[String Property List]], which could include the following options:


The second parameter is optional, it is a semicolon separated [[property string]], which could include the following parameters:
The '''temporary''' option dictates whether Maptool remembers the size of the frame between displays.  Setting this value to 1 causes Maptool to forget the window size.  Example "temporary=1"


The '''size''' parameter is a [[property string]] that contains two values, ''width'' and ''height''.  Those values can be measured in pixels ('''px''' and the default) or other HTML units, such as ems ('''em''') or screen width percentages ('''%''').
The '''title''' option sets the title of the frame and replaces the need to set the title from within the HTML code.


The following parameters work from v1.3b50 forward:
The '''tabtitle''' is the title shown when the frame is minimized. If not used as a parameter, the tabtitle is the same as the frame's title.


The '''input''' parameter dictates whether the dialog has a ''close'' button or is closed with an <input submit> button custom coded into the dialog. '''input''' is set to 1 or 0 within double quotes. example: "input=1"
The '''width''' and '''height''' options determine the (initial) size of the frame. Depending whether '''temporary''' has been set or not the frame will always open with these dimensions.


The '''temporary''' parameter dictates whether Maptool remembers the size of the dialog window between displays.  Setting this value to 1 causes Maptool to forget the window size. Example "temporary=1"
The '''scrollreset''' option, if equals to 1, resets the scrolling to the top of the frame once the frame is loaded with new HTML content.


The '''noframe''' parameter dictates whether the window has a frame or not.  Example "noframe=1" removes the frame from the dialog window.
The last parameter is '''value'''. It can be used to store some data inside the frame. For example, if a frame display the equipment of a character, the value parameter can be set to the token id of that character, so that you can know which character's equipment is being displayed.  


The '''title''' parameter sets the title of the dialog box and replaces the need to set the title from within the HTML code.
Prior to 1.5.4, using the '''title''' parameter when opening up a new frame could break the frame. Calls to the macro after closing the frame would not show the frame. This was remedied by adding a line to the calling macro before running the macro. The line below could be used, substituting your own frame name.
<syntaxhighlight lang="mtmacro" line>
[ if( isFrameVisible("YourFrame") ), code: {}; { [resetFrame("YourFrame")] } ]
</syntaxhighlight>
This checks if the bugged frame is visible or not. If the frame is open it does nothing, but if it is closed it resets the frame, which forces it to be shown. The bug is fixed from 1.5.4 onward.


|examples=
|examples=
The following code opens up a dialog window that contains the HTML as shown here:
Sample header
<syntaxhighlight lang="mtmacro" line>
[frame("Frame Test", "width=300; height=200; temporary=1;"): {
</syntaxhighlight>


[[Image:DialogEx1.png]]
The following code opens up a frame that contains the HTML as shown here:
 
<table>
<source lang="mtmacro" line>
<tr>
[dialog("Dialog Test"): {
<td>
[[Image:FrameDemo.png]]
</td>
<td>
<syntaxhighlight lang="mtmacro" line>
[frame("Frame Test"): {
   <html>
   <html>
     <head>
     <head>
       <title>Test of Dialog Windows</title>
       <title>Test of Frame Windows</title>
     </head>
     </head>
     <body>
     <body>
Line 48: Line 61:
   </html>
   </html>
} ]
} ]
</source>
</syntaxhighlight>
</td>
</tr>
</table>


To create a dialog that initially opens with a width of 300 pixels and height of 200 pixels, change the first line of the previous example to:
|also=
<source lang="mtmacro" line>
{{roll|frame5}} <br>
[dialog("Dialog Test", "width=300; height=200; temporary=1; input=0; noframe=1"): {
{{roll|dialog5}} <br>
</source>
{{roll|dialog}} <br>
{{func|isFrameVisible}} <br>
[[Introduction to Dialogs and Frames]]<br>
[[Forms tutorial]]


Did you try it?  It didn't change size from the previous example, did it?  Do you remember why?  If not, go back to the top of the page and read that first paragraph again!
|changes=
 
{{change|1.3b50|Added '''title''' parameter option.}}
|also=
{{change|1.5.4|Added '''temporary''', '''tabtitle''' and '''value''' parameter options.}}
{{change|1.7.0|Added '''scrollreset''' parameter option.}}


}}
}}
[[Category:Display Roll Option]]
[[Category:Display Roll Option]]
[[Category:Frame Function]]

Latest revision as of 23:59, 14 March 2023

[frame():] Roll Option

Opens a frame window supporting HTML3.2. Unlike the modal [dialog():], frames are dockable panels that are usually intended to remain open. Frames can be closed with a button located in the title bar or via the closeFrame() macro function.

Usage

[h: frame(frameName [,"width; height; temporary; title; tabtitle; scrollreset; value;"] )]

The first parameter, shown as frameName, should be a double-quoted string that specifies the internal name of the frame window. The visible title that appears in the title bar of the window is set separately, either by using HTML that appears inside the frame itself or use of the title parameter from b50 forward. Any attempts to open another frame with the same name instead cause the old contents to be removed and new contents displayed. Note this behavior relates to the internal name of the frame, not the displayed title of the frame as multiple frames can share a title. Once the named frame is opened and resized by the user, that size becomes its default opening size in the future, unless the temporary option is set to "1".


The second parameter is optional, it is a semicolon separated String Property List, which could include the following options:

The temporary option dictates whether Maptool remembers the size of the frame between displays. Setting this value to 1 causes Maptool to forget the window size. Example "temporary=1"

The title option sets the title of the frame and replaces the need to set the title from within the HTML code.

The tabtitle is the title shown when the frame is minimized. If not used as a parameter, the tabtitle is the same as the frame's title.

The width and height options determine the (initial) size of the frame. Depending whether temporary has been set or not the frame will always open with these dimensions.

The scrollreset option, if equals to 1, resets the scrolling to the top of the frame once the frame is loaded with new HTML content.

The last parameter is value. It can be used to store some data inside the frame. For example, if a frame display the equipment of a character, the value parameter can be set to the token id of that character, so that you can know which character's equipment is being displayed.

Prior to 1.5.4, using the title parameter when opening up a new frame could break the frame. Calls to the macro after closing the frame would not show the frame. This was remedied by adding a line to the calling macro before running the macro. The line below could be used, substituting your own frame name. 

[ if( isFrameVisible("YourFrame") ), code: {}; { [resetFrame("YourFrame")] } ]

This checks if the bugged frame is visible or not. If the frame is open it does nothing, but if it is closed it resets the frame, which forces it to be shown. The bug is fixed from 1.5.4 onward.

Examples

Sample header 

[frame("Frame Test", "width=300; height=200; temporary=1;"): {

The following code opens up a frame that contains the HTML as shown here: 

[frame("Frame Test"): {
  <html>
    <head>
      <title>Test of Frame Windows</title>
    </head>
    <body>
    <table border="1">
    <tr><th>Column 1</th><th>Column 2</th><th>Column 3</th></tr>
    <tr><td>Line 1, Col 1</td><td colspan="2">Line 1, Cols 2 and 3</td></tr>
    <tr><td rowspan="2">Lines 2 and 3, Col 1</td><td>Line 2, Col 2</td><td>Line 2, Col 3</td></tr>
    <tr><td>Line 3, Col 3</td><td>Line 3, Col 3</td></tr>
    </table>
    </body>
  </html>
} ]

See Also

[frame5():]
[dialog5():]
[dialog():]
isFrameVisible()
Introduction to Dialogs and Frames
Forms tutorial

Version Changes

  • 1.3b50 - Added title parameter option.
  • 1.5.4 - Added temporary, tabtitle and value parameter options.
  • 1.7.0 - Added scrollreset parameter option.
Retrieved from "https://wiki.rptools.info/index.php?title=frame_(roll_option)&oldid=34941"