VXPLib Documentation: QHTML |
QUICK HTML FOR APPLICATIONS 1.0 SPECIFICATION DOCUMENT
INTRODUCTION
SYNTAX
RESOURCE FILES
GRAPHICS
COLOR PALETTE
|
Tag name | Attribute name | Description | Default value |
|||
<FONT> | Changes the current font. Tag </FONT> closes the font tag, and selects the previously active font. Although it doesn't support property sheets, complete list of all necessary properties in combination with other tags - font modifiers allow to select any possible font installed on the computer. Additionally, you can select background and foreground colors for the font. | |||||
COLOR | The color attribute sets the color which text will appear in on the screen. | |||||
BGCOLOR | Sets background color of the text. It defaults to having the background color transparent. | |||||
FACE | Sets the typeface that will be used to display the text on the screen. | |||||
CHARSET | Specifies the character set, and can be whether an integer value or one of the following predefined values:
|
|||||
SIZE | Font size. A real size, or +/- can be specified for the current font size.
Examples: SIZE=12 - will set size 12 for the current font SIZE=+2 - will set the current font size equal to the size of the default font plus 2 SIZE=-4 - will set the current font size equal to the size of the default font minus 4 There is no limitation for the font size requested by this property. In combination with other tags that change the font style the user has full control over the font settings. The following example will select font 'Verdana' to be the current one, with size 12, Red text color, and it also will have bold italic style: <b><i><font face='Verdana' size=12 color=Red>Some Text</font></i></b> Will display: Some text |
|||||
WEIGHT | Specifies a relative font weight (boldness). Possible values: 100, 200, 300, 400, 500, 600, 700, 800, 900
It allows finer control of the font's boldness, rather than using tag <B> |
|||||
<B> | Selects the current font to be bold. This tag has no parameters, and has the same effect is if you were specifying attribute WEIGHT=700 for tag <FONT>. To return the current font to its previous state use tag </B>. | |||||
<I> | Selects italic font. Use tag </I> to select the previous font style. This tag has no parameters. | |||||
<U> | Selects underlined font. Use tag </U> to select the previous font style. This tag has no parameters. | |||||
<
S>, <STRIKE> | Selects stricken font. Use tag </S> or </STRIKE> to select the previous font style. This tag has no parameters. | |||||
<BR> | Begins a new line. The amount of line space used is the same as height of the currently selected font. This tag has no parameters. It is a specific of the parser opposed to Internet Browsers that it never begins a new line automatically no matter how long the current line is. The parser can begin a new line only by using tags <BR> and <HR>. | |||||
<HR> | A Horizontal Rule element - is a divider between sections of text such as a full width horizontal rule or equivalent graphic. | |||||
SIZE | The SIZE attribute allows to specify how thick they wish the horizontal rule to be. | 2 | ||||
WIDTH | Width of the horizontal rule in percent of the space available for the rule context. Adding symbol % is not required. | 100% | ||||
ALIGN | One of the values: LEFT, RIGHT, CENTER | LEFT | ||||
COLOR | Color of the horizontal rule. | Black | ||||
SHAPE | Shape of the horizontal rule. Allows three possible forms of appearance for the divider: RECT - rectangle shape ROUND - rounded shape ELLIPSE - ellipse shape |
RECT | ||||
<TABLE> | Opens a new table. If the table is not followed by tag </TABLE> all contents of such table will be ignored. The parser supports embedded declarations table-within-table of any depth. | BORDER | Width of the table border in pixels. | 0 | ||
BORDERCOLOR | Color of the table border.
Note: The parser also recognizes abbreviation BC for this attribute. |
Black | ||||
BGCOLOR | Color of the table background. Transparent by default when used on its own, and Black when attribute GFC is used. | Black | ||||
CELLSPACING | The CELLSPACING is the amount of space inserted between individual table data cells (table grid width).
Note: The parser also recognizes abbreviation CS for this attribute. |
0 | ||||
CELLPADDING | The CELLPADDING is the amount of white space between the borders of the table cell and the actual cell data
Note: The parser also recognizes abbreviation CP for this attribute. |
2 | ||||
BACKGROUND | Background picture for the entire table, if the RES property is not specified, or resource file,
if RES is specified.
Note: The parser also recognizes abbreviation BG for this attribute. | |||||
GFC | Gradient Fill Color. Fills the table using gradient color effect from color BGCOLOR to GFC. It defaults to Black color, but won't work unless set explicitly. | Black | ||||
GRAD | Gradient fill direction. Can be one of two values: HOR or VERT to specify Horizontal or Vertical gradient accordingly. | HOR | ||||
RES | Redirects source of the background picture to a resource file. Format examples: RES='JPEG=#192' - will allocate a resource type JPEG in the resource file, and resource with number 192. RES='GIF=IDG_MAINGIF' - will allocate a resource type GIF in the resource file, and resource with name IDG_MAINGIF. When RES is used, contents of BACKGROUND is treated as a resource file. If BACKGROUND is not specified, the default resource file is used. | |||||
<TR> | Opens a new row in the table. If the row is not followed by </TR> all contents of such row will be ignored. | |||||
ALIGN | Horizontally aligns contents of the table row. Possible values: LEFT, RIGHT, CENTER | LEFT | ||||
VALIGN | Vertically aligns contents of the table row. Possible values: TOP, MIDDLE, BOTTOM | TOP | ||||
BGCOLOR | Background color of the entire row. Transparent by default when used on its own, and Black when attribute GFC is used. | |||||
BACKGROUND | Background picture for the entire row, if the RES property is not specified, or resource file, if RES is specified.
Note: The parser also recognizes abbreviation BG for this attribute. |
|||||
GFC | Gradient Fill Color. Fills the row using gradient color effect from color BGCOLOR to GFC. It defaults to Black color, but won't work unless set explicitly. | Black | ||||
GRAD | Gradient fill direction. Can be one of two values: HOR or VERT to specify Horizontal or Vertical gradient accordingly. | HOR | ||||
RES | The same as for tag <TABLE>, property RES. | |||||
<TD> | Opens a new column in the table. If the column is not followed by </TD> all contents of such column will be ignored. | |||||
ALIGN | Horizontally aligns contents of the cell. Possible values: LEFT, RIGHT, CENTER | LEFT | ||||
VALIGN | Vertically aligns contents of the cell. Possible values: TOP, MIDDLE, BOTTOM | TOP | ||||
BGCOLOR | Background color of the cell. Transparent by default when used on its own, and Black when attribute GFC is used. | |||||
BACKGROUND | Background picture for the cell, if the RES property is not specified, or resource file, if RES is specified.
Note: The parser also recognizes abbreviation BG for this attribute. |
|||||
GFC | Gradient Fill Color. Fills the cell using gradient color effect from color BGCOLOR to GFC. It defaults to Black color, but won't work unless set explicitly. | Black | ||||
GRAD | Gradient fill direction. Can be one of two values: HOR or VERT to specify Horizontal or Vertical gradient accordingly. | HOR | ||||
RES | The same as for tag <TABLE>, property RES. | |||||
WIDTH | Minimum width of the cell. If the cell's contents is wider than the specified with, the cell width is enlarged to its contents width. | 0 | ||||
HEIGHT | Minimum height of the cell. If the cell's contents doesn't fit in the specified height, the cell height is enlarged to its contents height. | 0 | ||||
< IMG> | The image element for in-line graphics. Officially supported formats: BMP, ICO, CUR, ANI, EMF and WMF. Unofficially supported formats: JPEG, GIF, ... etc., all formats supported by the IPicture interface in the system. Read Graphics | |||||
SRC | Picture file name, if the RES property is not specified, or resource file containing the picture, if RES is specified. | "" | ||||
ALT | An alternative text to appear instead of the picture when the picture is not found. Currently selected font is used for that. | "" | ||||
RES | The same as for tag <TABLE>,
property RES, except for the Windows Standard Resources when the resource type name must be one of the following:
BMP for bitmaps, ICO for icons, CUR for cursors, and ANI for animation files.
Example: <IMG RES='ICO:IDR_MYICON'> - will load an icon with name IDR_MYICON from the default resource file. |
"" | ||||
BORDER | Border width to surround the picture. | 0 | ||||
WIDTH | Sets exact width of the picture in pixels. Defaults to the picture's original width. | |||||
HEIGHT | Sets exact height of the picture in pixels. Defaults to the picture's original height. | |||||
BGCOLOR | Background color for the picture. Can be seen when the picture fails to load, or when a picture with transparent background is used. Transparent by default when used on its own, and Black when attribute GFC is used. | |||||
GFC | Gradient Fill Color. Fills background of the picture using gradient color effect from color BGCOLOR to GFC. It defaults to Black color, but won't work unless set explicitly. | Black | ||||
GRAD | Gradient fill direction. Can be one of two values: HOR or VERT to specify Horizontal or Vertical gradient accordingly. | HOR | ||||
BORDERCOLOR | Color of the picture border, if such presents.
Note: The parser also recognizes abbreviation BC for this attribute. |
Black | ||||
<TXT> | Dynamic text tag. It can load text from any source, format it, and insert instead of itself. When property ID is used the QHTML parser is trying to retrieve text from an abstract source, thus making it possible to get the text from anywhere (read property ID). | |||||
FILE | When property RES is not specified it refers to a text or HTML file.
When RES is specified it refers to a resource file. Examples: 1) <txt file='readme.txt'> - will load a text file with name readme.txt and apply auto-formatting to it. 2) <txt file='readme.txt' size=100 format=none> - will try to load the first 100 bytes from a text file with name readme.txt without applying any formatting to it. |
|||||
RES | When property FILE is not specified it refers to a text or HTML resource in the default
resource file. Otherwise, it refers to a resource in the file specified by property FILE. Examples: 1) <txt res=#57604> - will load a string with ID 57604 from the default resource file and apply auto-formatting to it. 2) <txt res='html:idr_mydoc'> - will load an HTML document with name idr_mydoc from the default resource file and apply auto-formatting to it. 3) <txt res='html=idr_mydoc' file='myres.dll' format=html> - will load an HTML document with name idr_mydoc from resource file myres.dll, and apply HTML formatting to it. |
|||||
FORMAT | Formats the loaded text in one of the four possible ways: NONE - no formatting to be applied SIMPLE - applies simple formatting as one applicable to a text file when symbol '\n' is simply replaced by tag <BR> HTML - applies HTML formatting to the loaded text. AUTO - the parser will scan the text to find out whether it is HTML or plain text, and apply whether HTML or SIMPLE formatting accordingly. |
AUTO | ||||
CODEPAGE | This attribute provides for multilingual text support. The parser can select a code page individually for each tag <TXT>.
When this attribute is not specified the parser uses its property TxtCodePage as the default code page. Examples:
1. The parser also recognizes abbreviation CP for this attribute. 2. Avoid using attributes CODEPAGE and ID at the same time with fonts that require Wide Char or Unicode presentation. |
0 | ||||
SIZE | When text is loaded from an external file a size limit can be forced to apply. When the size is set to
0 no size limit applies. Otherwise, this property specifies the number of bytes that can be read from the file.
Note: In the current version setting size to 0 is the same as setting to 65536, which defines the maximum file size. However, the maximum size can be modified in the future whilst the meaning of size 0 will remain the same. |
0 | ||||
ID | When specified changes the way parser treats tag TXT. Instead the parser assumes that the tag refers to a virtual
text source, which can be anything, and only the client application knows how to retrieve that information from the
source. For instance, such tag can imply a reference to an SQL server containing some sort of records where the ID parameter then
can be treated as a record ID. In any way, when ID is specified the parser fires event OnGetText expecting from the client application
to handle this event, and return a text string in the end. In the meantime, the parser assumes the following:
|
0 | ||||
<DOC> | Dynamic document. Allows to insert a dynamic (virtual) document right into the QHTML context.
Such document supports custom drawing, thus makes it possible to display any document the client application
is aware of.
When the QHTML parser finds this tag it fires event OnDocumentGetSize to get dimensions
of the document. The client application is supposed to handle such event and respond correctly by setting Width and Height
of the document. If both Height and Width are different from 0 after this, the document will be drawn through the OnDocumentDraw event.
The QHTML parser expects the client to handle this event in order to draw the document's contents. |
|||||
FILE | An optional parameter to support file documents. When specified it must contain a file name located in whether the current directory or in a directory from the list constructed by AddFilePath. If the specified file cannot be found, the html parser will be passing an empty string for the first parameter of events OnDocumentGetSize and OnDocumentDraw. If the parser finds the file, it will be passing the full file path. | "" | ||||
PARAM | An optional text string to pass extra information in OnDocumentGetSize and OnDocumentDraw. For example, it may contain a number that will identify the type of the document, or in one way or another telling the two event handlers how to treat the document. It can be any information the developer may decide useful, or just not to use this parameter at all. The contents of PARAM will be passed in OnDocumentGetSize and OnDocumentDraw as the second parameter. | "" | ||||
WIDTH | Specifies the width of the document in pixels. This value will be passed in OnDocumentGetSize. When not specified in the tag the client application must handle event OnDocumentGetSize to set a correct value for the document width. If both the WIDTH and HEIGHT parameters are specified in the tag, the client application doesn't need to handle OnDocumentGetSize, although it can in order to override the values passed in the tag. If after calling OnDocumentGetSize one of the parameters WIDTH and HEIGHT is set to 0, event OnDocumentDraw won't happen for such document. | 0 | ||||
HEIGHT | Specifies the height of the document in pixels. For more information read about property WIDTH. | 0 | ||||
BORDER | Document border width. Each virtual document can have a frame of specified width around it. When OnDocumentDraw is called its X and Y parameters will contain (X + BORDER) and (Y + BORDER), and Width and Height of the document will contain (Width - BORDER * 2) and (Height - BORDER * 2), i.e. the document size will be increased by the size of BORDER * 2. | 0 | ||||
BORDERCOLOR | Color of the document border when BORDER is more than 0.
Note: The parser also recognizes abbreviation BC for this attribute. |
Blue | ||||
BGCOLOR | Color of the document background. When OnDocumentDraw is called the document's background has been filled with
the specified color. It is an optional attribute, and if not specified, the document's background won't be drawn at all, i.e. it will have
the background of the object on which the document is drawn. Defaults to Black when attribute GFC is used. |
|||||
GFC | Gradient Fill Color. Fills background of the document using gradient color effect from color BGCOLOR to GFC. It defaults to Black color, but won't work unless set explicitly. | Black | ||||
GRAD | Gradient fill direction. Can be one of two values: HOR or VERT to specify Horizontal or Vertical gradient accordingly. | HOR | ||||
BACKGROUND | Background picture for the document, if the RES property is not specified, or resource file, if RES is specified.
Note: The parser also recognizes abbreviation BG for this attribute. |
"" | ||||
RES | The same as for tag <TABLE>, property RES. | "" | ||||
<CONTROL> |
Embedded Windows Control. It assigns a placeholder within QHTML to a windows control of specified size (attributes WIDTH and HEIGHT).
By using dimensions of the control the parser will be able to reserve place of the exact size within QHTML while applying all
formatting and alignment operations to it. In order to position correctly the actual control within QHTML a client application should retrieve the exact position of the
control in the document by using function
GetControlPos of the parser. Besides the standard attributes described below a client application also can access any custom attribute defined in the tag by using function GetControlAttr or GetControlAttrIdx. When this tag refers to a windows control of dynamically calculated size (when attributes WIDTH and HEIGHT are not specified) the client will have to handle event OnControlGetSize to tell the parser the exact size of the control. |
|||||
ID | An integer value (positive or negative) different from 0 to uniquely identify this control tag from any other control tags. This value is to be used as a parameter to functions GetControlAttr and GetControlPos of the parser. | 0 | ||||
WIDTH | Width of the control in pixels, if it can be specified at design time. If width of the control is unknown the client will have to handle event OnControlGetSize to provide information about width of the control dynamically. | 0 | ||||
HEIGHT | Height of the control in pixels, if it can be specified at design time. If height of the control is unknown the client will have to handle event OnControlGetSize to provide information about height of the control dynamically. | 0 | ||||
NAME | An optional text string attribute to be passed as a parameter of event OnControlGetSize. A possible use of it is when a control is created dynamically to pass a class name for the control to be created. | "" | ||||
PARAM | An optional text string attribute to be passed as a parameter of event OnControlGetSize. A possible use of it is when a control is created dynamically to pass an initialization parameter for the control to be created. | "" | ||||
<BODY> | Unlike in the standard HTML specification, this tag doesn't open contents
of the document with implication to close the document's contents where </BODY> is met. This tag inherited its name
from the standard <BODY> tag because it defines global parameters applicable to the whole QHTML contents.
This tag is optional, and can be placed into any position inside the QHTML document, and will be recognized correctly. If the QHMTL parser
finds more than one <BODY> tag in the QHTML document, it will process only the very first one it meets, and all the following
tags <BODY> will be ignored. Because this tag only defines the QHTML document properties it doesn't need to be closed by
</BODY> Interface IVXPQuickHTML selects default values for all parameters of tag <BODY> and all the rest settings by firing event OnSetDefaults. It assumes that a client application or interface will handle this event to setup all the default properties for tag <BODY> and all the rest default settings of the IVXPQuickHTML interface. IVXPQuickHTML fires event OnSetDefaults before it starts processing tag <BODY>, which means that defining tag <BODY> in the QHTML document allows to override some of the default parameters. It doesn't allow to override all the default parameters, only those specified for this tag. In order to be able to setup default values for all the rest parameters the client will have to handle event OnSetDefaults. Such parameters as margins are to be used by client applications only. Their value do not in any way effect the way IVXPQuickHTML draws the document. IVXPTooltip is a client example of using values of margins when drawing a tooltip. Besides standard attributes of the tag as described below a client application also can specify any custom attribute, access to which is provided through function GetBodyAttr. |
|||||
TEXT | Default text color in the QHTML document. If not specified in the <BODY> tag, its value is supposed to be set inside the client's implementation of OnSetDefaults, which, for instance, in case of IVXPTooltip it will be the tooltip text color set in the system. | Black | ||||
FONT | Specifies which system font the parser will use as the default one: CAPT - Caption font in the system used for displaying text in window titles. SCAPT - Small Caption font in the system used for displaying text within small window titles such as toolbar captions. MENU - Menu font used in the system for displaying text in menu bars. TOOL - Tooltip font used in the system for displaying text in tooltips. SBAR - Status Bar font used in the system for displaying text in window status bars. MSG - Message box font used in the system for displaying text in dialog and message boxes.
|
MSG | ||||
BGCOLOR | Background color of the entire QHTML document. Similar to property TEXT its value is set within OnSetDefaults of the client application or interface. | White | ||||
GFC | Gradient Fill Color. Fills the entire QHTML document using gradient color effect from color BGCOLOR to GFC. It defaults to Black color, but won't work unless set explicitly. | Black | ||||
GRAD | Gradient fill direction. Can be one of two values: HOR or VERT to specify Horizontal or Vertical gradient accordingly. | HOR | ||||
LEFTMARGIN | Left hand margin of the document to be used by client applications. The value doesn't effect drawing by IVXPQuickHTML.
Note: The parser also recognizes abbreviation LM for this attribute. |
0 | ||||
RIGHTMARGIN | Right hand margin of the document to be used by client applications. The value doesn't effect drawing by IVXPQuickHTML.
Note: The parser also recognizes abbreviation RM for this attribute. |
0 | ||||
TOPMARGIN | Top margin of the document to be used by client applications. The value doesn't effect drawing by IVXPQuickHTML.
Note: The parser also recognizes abbreviation TM for this attribute. |
0 | ||||
BOTTOMMARGIN | Bottom margin of the document to be used by client applications. The value doesn't effect the way IVXPQuickHTML draws.
Note: The parser also recognizes abbreviation BM for this attribute. |
0 | ||||
BACKGROUND | Background picture for the whole contents drawn by IVXPQuickHTML, if the RES property is not specified, or resource file, if RES is specified.
Note: The parser also recognizes abbreviation BG for this attribute. |
"" | ||||
RES | The same as for tag <TABLE>, property RES. | "" | ||||
<BGSOUND> | Background Sound settings. These settings can be used by client applications to provide a sound effect
unique for each contents of IVXPQuickHTML. When specified, this tag is managed by the IVXPSound
interface available through settings->bgsound.
Interface IVXPTooltip is an example of using tag <BGSOUND> to play sound attuned with the tooltip's fading status.
Read documentation on the IVXPSound interface for more details. |
|||||
FILE | A sound file, if RES is not specified, or a resource file, if RES is specified. | "" | ||||
RES | Sound resource in the default resource, if FILE is not specified, or in the resource file specified by parameter FILE. Format examples:
|
"" | ||||
PARAM | Any parameter that can be useful in playing the sound. | 0 | ||||
PLAYFROM | Defines contents of parameter Handle of the IVXPSound interface
after the parser has finished processing tag <BGSOUND>:
|
CUSTOM | ||||
SIZE | The size limit for the sound data to be loaded into memory. Allows setting a limit on loading huge amount of sound data into memory at once. The value of 0 indicates that no limit applies. | 0 | ||||
VOLUME | Defines a virtual volume parameter of the sound. | 0xFFFFFFFF | ||||
BALANCE | Defines a virtual balance parameter of the sound. | 0 | ||||
FREQUENCY | Defines a virtual frequency parameter of the sound. | 0 | ||||
STARTPOS | When working with a multi-record sound source defines a virtual start position in the source for the current sound record. | 0 | ||||
ENDPOS | When working with a multi-record sound source defines a virtual end position in the source for the current sound record. | 0 | ||||
LOOP | Defines how many times the sound must be played. The value of 0 indicates that the sound must be played in a never-ending loop. | 1 | ||||
DELAY | Defines a virtual delay before the sound must begin. | 0 | ||||
PAUSE | If LOOP <> 1, defines a virtual pause between the end of playing the sound and beginning to play it again. | 0 | ||||
INFO | A text string to contain any information about the sound. For instance, if we play songs it can be the song name. | "" | ||||
<!...> | Comment block. Whatever is inside between <! and > is considered as a comment block, and not analyzed.
When drawing a document the parser skips contents of such tags. The idea of this tag is to serve two purposes:
|
|||||
<&...> | Speech tag. Whatever inside the tag the parser treats as a Text-To-Speech contents.
This speech contents is to be read using function GetSpeechText This is another invisible tag, which can be considered a comment tag, but relating only to using speech. |