| Top | |
|
|
|
Graphics in Text Buffer WindowsGraphics in Text Buffer Windows — Drawing graphics inside or beside text |
| #define | imagealign_InlineUp |
| #define | imagealign_InlineDown |
| #define | imagealign_InlineCenter |
| #define | imagealign_MarginLeft |
| #define | imagealign_MarginRight |
A text buffer is a linear text stream. You can draw images in-line with this text. If you are familiar with HTML, you already understand this model. You draw images with flags indicating alignment. The library takes care of scrolling, resizing, and reformatting text buffer windows.
If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
window, val1
gives the image alignment. The val2
argument is currently
unused, and should always be zero.
The two “margin” alignments require some care.
To allow proper positioning, images using imagealign_MarginLeft and
imagealign_MarginRight must be placed at the beginning of a line.
That is, you may only call glk_image_draw() (with these two alignments) in a
window, if you have just printed a newline to the window's stream, or if the
window is entirely empty.
If you margin-align an image in a line where text has already appeared, no
image will appear at all.
Inline-aligned images count as “text” for the purpose of this rule.
You may have images in both margins at the same time.
It is also legal to have more than one image in the same margin (left or right.) However, this is not recommended. It is difficult to predict how text will wrap in that situation, and libraries may err on the side of conservatism.
void
glk_window_flow_break (winid_t win);
You may wish to “break” the stream of text down below the current margin image. Since lines of text can be in any font and size, you cannot do this by counting newlines. Instead, use this function.
If the current point in the text is indented around a margin-aligned image, this acts like the correct number of newlines to start a new line below the image. (If there are several margin-aligned images, it goes below all of them.) If the current point is not beside a margin-aligned image, this call has no effect.
When a text buffer window is resized, a flow-break behaves cleverly; it may become active or inactive as necessary. You can consider this function to insert an invisible mark in the text stream. The mark works out how many newlines it needs to be whenever the text is formatted for display.
An example of the use of glk_window_flow_break(): If you display a
left-margin image at the start of every line, they can stack up in a strange
diagonal way that eventually squeezes all the text off the screen.
If you can't picture this, draw some diagrams. Make the margin images more than one line tall, so that each line starts already indented around the last image.
To avoid this problem, call glk_window_flow_break() immediately before
glk_image_draw() for every margin-aligned image.
In all windows other than text buffers, glk_window_flow_break() has no
effect.
This function is not implemented yet.
#define imagealign_InlineUp (0x01)
The image appears at the current point in the text, sticking up. That is, the bottom edge of the image is aligned with the baseline of the line of text.
#define imagealign_InlineDown (0x02)
The image appears at the current point, and the top edge is aligned with the top of the line of text.
#define imagealign_InlineCenter (0x03)
The image appears at the current point, and it is centered between the top and baseline of the line of text. If the image is taller than the line of text, it will stick up and down equally.
#define imagealign_MarginLeft (0x04)
The image appears in the left margin. Subsequent text will be displayed to the right of the image, and will flow around it — that is, it will be left-indented for as many lines as it takes to pass the image.
Margin images are not implemented yet.