1 /* Monolith window class.
2 * - by Richard W.M. Jones <rich@annexia.org>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the Free
16 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 * $Id: ml_window.h,v 1.8 2003/04/30 13:15:34 rich Exp $
24 #include <pthr_iolib.h>
25 #include <pthr_http.h>
26 #include <ml_widget.h>
29 typedef struct ml_window *ml_window;
33 struct ml_frame_description
35 void (*fn) (struct ml_session *, void *data);
39 /* Function: new_ml_window - monolith windows, framesets, redirects
40 * Function: ml_window_pack
41 * Function: ml_window_set_headers_flag
42 * Function: ml_window_get_headers_flag
43 * Function: ml_window_set_title
44 * Function: ml_window_get_title
45 * Function: ml_window_set_stylesheet
46 * Function: ml_window_get_stylesheet
47 * Function: ml_window_set_charset
48 * Function: ml_window_get_charset
49 * Function: ml_window_set_refresh
50 * Function: ml_window_get_refresh
51 * Function: ml_window_scroll_to
52 * Function: new_ml_frameset
53 * Function: ml_frameset_set_description
54 * Function: ml_frameset_set_title
55 * Function: ml_frameset_get_title
56 * Function: new_ml_redirect
57 * Function: ml_redirect_set_uri
58 * Function: ml_redirect_get_uri
60 * A "window" is a top-level window. Every application has at
61 * least one window, created in the main function. A window is
62 * just a wrapper. To actually do anything, you must pack a
63 * single widget inside the window. Windows can only take a
64 * single widget. If you want more than one widget to appear
65 * inside a window, then you must pack them into some sort
66 * of layout widget first, and pack the layout widget into
69 * A "frameset" is used to create framesets (several ordinary
70 * windows packed into one top-level window, with independent
71 * scrolling capabilities). Framesets may contain windows or
72 * other framesets, or a mixture of both.
74 * A "redirect" is a window/frame that shows a static page
75 * (in fact anything which can be reached using a URI - pages, images,
76 * CGI scripts, even other Monolith applications).
78 * Windows, framesets and redirects are actually so
79 * similar, that I have included them in the same class (and also so
80 * that other code can deal with an opaque @code{ml_window} pointer
81 * and not have to worry about whether it is a window,
84 * Monolith windows are not widgets (unlike many of the
85 * other classes in monolith).
87 * @code{new_ml_window} creates a new monolith window.
89 * @code{ml_window_pack} packs a widget into the window. Since a
90 * window can only contain a single widget, subsequent calls to
91 * this function overwrite the packed widget. (Note: this call
92 * does not apply to framesets).
94 * @code{ml_window_(set|get)_headers_flag} is a somewhat esoteric flag
95 * that you will almost never need to change. When set (the default),
96 * the window widget outputs the opening @code{<html>}, @code{<head/>},
97 * @code{<body>} and closing @code{</body>}, @code{</html>}. If
98 * cleared, then these are not output. Almost the only place where it
99 * is useful to clear this flag is when using the @code{ml_msp}
100 * (monolith server-parsed pages) widget directly inside a window
101 * (see @ref{new_ml_msp(3)}).
103 * @code{ml_window_(set|get)_title} changes the title of
104 * the window. The title of the window defaults to no title
105 * at all, so it is a good idea to set this.
107 * @code{ml_window_(set|get)_stylesheet} changes the stylesheet
108 * of the page. Monolith default stylesheets are installed in
109 * @code{/ml-styles/}, and the default stylesheet is
110 * @code{/ml-styles/default.css} (supplied in the monolith
111 * distribution). Stylesheets are used to 'theme' monolith
114 * @code{ml_window_(set|get)_charset} changes the character
115 * encoding associated with the window. Because of limitations
116 * in HTML, only a single charset can be associated with all
117 * of the widgets in a window. The default charset is
120 * @code{ml_window_(set|get)_refresh} changes the refresh
121 * period. This is an integer representing a number of seconds.
122 * If this is greater than zero, then the browser will automatically
123 * refetch the page after this many seconds. The default is zero
124 * which means no automatic refresh. It is not recommended that
125 * you set this in ordinary applications.
127 * @code{ml_window_scroll_to} scrolls the window to the absolute
128 * (@code{x}, @code{y}) pixel position given. This is not supported by
131 * @code{new_ml_frameset} creates a new frameset. @code{rows} and
132 * @code{cols} define the number of frames and their layout. You can
133 * use @code{rows} and @code{cols} to create frameset layouts
134 * including grids, as described in the HTML 4 standard
135 * (@code{http://www.w3.org/TR/html401/}). To create nested framesets,
136 * use a frame which generates a frameset instead of a
137 * window. @code{frames} is a vector of @code{struct ml_frame_description}
138 * structures (note: the structures themselves, not pointers to the
139 * structures). @code{struct ml_frame_description} contains the
142 * @code{fn}: The function which is called generate the frame
143 * (or nested frameset). This function must call either
144 * @code{new_ml_window} or @code{new_ml_frameset}. The function
145 * is prototyped as @code{void fn (ml_session session, void *data);}.
147 * @code{data}: Data pointer passed to this function.
149 * @code{ml_frameset_set_description} allows the frameset description
152 * @code{ml_frameset_(set|get)_title} updates the window title.
154 * @code{new_ml_redirect} creates a new redirect. @code{uri}
155 * is the URI of the static page (etc.) containing the actual
156 * content for this window/frame.
158 * @code{ml_redirect_(set|get)_uri} updates the URI of the static
159 * page being displayed. Note that setting the URI will not necessarily
160 * repaint the contents of the window.
162 * See also: @ref{ml_ok_window(3)}.
164 extern ml_window new_ml_window (struct ml_session *, pool pool);
165 extern void ml_window_pack (ml_window, ml_widget);
166 extern void ml_window_set_headers_flag (ml_window, int headers_flag);
167 extern int ml_window_get_headers_flag (ml_window);
168 extern void ml_window_set_title (ml_window, const char *title);
169 extern const char *ml_window_get_title (ml_window);
170 extern void ml_window_set_stylesheet (ml_window, const char *stylesheet);
171 extern const char *ml_window_get_stylesheet (ml_window);
172 extern void ml_window_set_charset (ml_window, const char *charset);
173 extern const char *ml_window_get_charset (ml_window);
174 extern void ml_window_set_refresh (ml_window, int refresh);
175 extern int ml_window_get_refresh (ml_window);
176 extern void ml_window_scroll_to (ml_window, int x, int y);
177 extern ml_window new_ml_frameset (struct ml_session *, pool pool, const char *rows, const char *cols, vector frames);
178 extern void ml_frameset_set_description (ml_window, struct ml_session *, const char *rows, const char *cols, vector frames);
179 extern void ml_frameset_set_title (ml_window, const char *);
180 extern const char *ml_frameset_get_title (ml_window);
181 extern ml_window new_ml_redirect (struct ml_session *, pool pool, const char *uri);
182 extern void ml_redirect_set_uri (ml_window, const char *uri);
183 extern const char *ml_redirect_get_uri (ml_window);
185 /* Internal functions to repaint the window. */
186 extern void _ml_window_notify_begin_response (ml_window w);
187 extern int _ml_window_get_response_code (ml_window w);
188 extern const char *_ml_window_get_response_name (ml_window w);
189 extern void _ml_window_set_cookie_with_javascript (ml_window w, const char *cookie);
190 extern void _ml_window_send_headers (ml_window w, pool thread_pool, http_response http_response);
191 extern void _ml_window_repaint (ml_window, struct ml_session *, io_handle);
193 /* Internal function to get the current windowid - used in a very few,
194 * quite rare places in monolith widgets.
196 extern const char *_ml_window_get_windowid (ml_window);
198 #endif /* ML_WINDOW_H */