aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/header.html2
-rw-r--r--doc/layout.xml2
-rw-r--r--doc/mainpage.md60
-rw-r--r--doc/reference.doxygen.in6
-rw-r--r--doc/style.css322
5 files changed, 238 insertions, 154 deletions
diff --git a/doc/header.html b/doc/header.html
index 07d4076..54c25b0 100644
--- a/doc/header.html
+++ b/doc/header.html
@@ -41,7 +41,9 @@
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
+ <li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
+ <li><a href="functions.html"><span>Symbols</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
diff --git a/doc/layout.xml b/doc/layout.xml
index f752de1..1889302 100644
--- a/doc/layout.xml
+++ b/doc/layout.xml
@@ -83,6 +83,7 @@
<!-- Layout definition for a namespace page -->
<namespace>
<briefdescription visible="yes"/>
+ <detaileddescription title=""/>
<memberdecl>
<nestednamespaces visible="yes" title=""/>
<constantgroups visible="yes" title=""/>
@@ -93,7 +94,6 @@
<variables title=""/>
<membergroups visible="yes"/>
</memberdecl>
- <detaileddescription title=""/>
<memberdef>
<inlineclasses title=""/>
<typedefs title=""/>
diff --git a/doc/mainpage.md b/doc/mainpage.md
index 2e90050..3c4bab6 100644
--- a/doc/mainpage.md
+++ b/doc/mainpage.md
@@ -1,36 +1,52 @@
This is the API documentation for Pugl.
-The complete C API is documented in the [Pugl](@ref pugl) group,
-and the C++ wrapper in the [Puglxx](@ref puglxx) group.
+This documentation is based around the [C API](@ref pugl_api),
+there is also a [C++ API](@ref pugl) in the `pugl` namespace.
The Pugl API revolves around two main objects:
the [World](@ref world) and the [View](@ref view).
-An application creates a single world to manage system-level state,
+An application creates a single world to manage top-level state,
then creates one or more views to display.
-## View creation
+## World
+
+The [World](@ref world) contains all top-level state,
+and manages views and the event loop.
+
+A world must be [created](@ref puglNewWorld) before any views,
+and it must outlive all views.
+
+## View
+
+A [View](@ref view) is a drawable region that receives events.
Creating a visible view is a multi-step process.
-A new view allocated with #puglNewView does not yet represent a "real" system window.
-To display, it must first have a [backend set](@ref puglSetBackend),
+When a new view is [created](@ref puglNewView),
+it does not yet represent a real system view or window.
+To display, it must first have a [backend](@ref puglSetBackend)
+and [event handler](@ref puglSetEventFunc) set,
and be configured by [setting hints](@ref puglSetViewHint)
-and [configuring the frame](@ref frame).
+and optionally [adjusting the frame](@ref frame).
+
+The [Backend](@ref PuglBackend) controls drawing for a view.
+Pugl includes [Cairo](@ref cairo) and [OpenGL](@ref gl) backends,
+as well as a [stub](@ref stub) backend that creates a native window with no drawing context.
-Once the view is configured,
-the corresponding window can be [created](@ref puglCreateWindow)
-and [shown](@ref puglShowWindow).
-Note that a view does not necessary correspond to a top-level system window.
+Once the view is configured,
+it can be [created](@ref puglCreateWindow) and [shown](@ref puglShowWindow).
+By default a view will correspond to a top-level system window.
To create a view within another window,
-call #puglSetParentWindow before #puglCreateWindow.
+it must have a [parent window set](@ref puglSetParentWindow) before being created.
+
+
+## Events
-## Interaction
+[Events](@ref events) are sent to a view when it has received user input or must be drawn.
-Interaction with the user and system happens via [events](@ref interaction).
-Before creating a window,
-a view must have an [event handler](@ref PuglEventFunc) set with #puglSetEventFunc.
-This handler is called whenever something happens that the view must respond to.
+Events are handled by the [event handler](@ref PuglEventFunc) set during initialisation.
+This function is called whenever something happens that the view must respond to.
This includes user interaction like mouse and keyboard input,
-and system events like window resizing and exposure (drawing).
+and system events like window resizing and exposure.
## Event Loop
@@ -39,5 +55,9 @@ Two functions are used to drive the event loop:
* #puglPollEvents waits for events to become available.
* #puglDispatchEvents processes all pending events.
-Redrawing is accomplished by calling #puglPostRedisplay,
-which posts an expose event to the queue.
+Redrawing is accomplished by calling #puglPostRedisplay or #puglPostRedisplayRect,
+which post expose events to the queue.
+
+## Error Handling
+
+Most functions return a [Status](@ref status) which should be checked to detect failure.
diff --git a/doc/reference.doxygen.in b/doc/reference.doxygen.in
index eb64d58..47781a4 100644
--- a/doc/reference.doxygen.in
+++ b/doc/reference.doxygen.in
@@ -692,7 +692,7 @@ SHOW_FILES = YES
# Folder Tree View (if specified).
# The default value is: YES.
-SHOW_NAMESPACES = NO
+SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from
@@ -1451,7 +1451,7 @@ GENERATE_TREEVIEW = NO
# Minimum value: 0, maximum value: 20, default value: 4.
# This tag requires that the tag GENERATE_HTML is set to YES.
-ENUM_VALUES_PER_LINE = 1
+ENUM_VALUES_PER_LINE = 0
# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used
# to set the initial width (in pixels) of the frame in which the tree is shown.
@@ -2090,7 +2090,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-PREDEFINED = PUGL_API PUGL_DEPRECATED_BY
+PREDEFINED = PUGL_API PUGL_DISABLE_DEPRECATED
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
diff --git a/doc/style.css b/doc/style.css
index b01bdb4..ae62d19 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -7,33 +7,114 @@ body {
margin-right: auto;
padding: 1em;
max-width: 60em;
- font-family: "DejaVu Serif",Palatino,serif;
+ font-family: "DejaVu Sans", Verdana, Helvetica, Arial, sans-serif;
text-rendering: optimizeLegibility;
}
-h1, .title, #projectname, h2, h3, h4, h5, h6 {
- line-height: 1.0125em;
+h1 {
+ font-size: 1.68em;
+ font-weight: 500;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
+ line-height: 2em;
+ margin: 0 0 0.25em 0;
+}
+
+h2 {
+ line-height: 1.68em;
+ font-size: 1.41em;
+ font-weight: 600;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
+ margin: 1.25em 0 0.5em 0;
+}
+
+h3 {
+ line-height: 1.41em;
+ font-size: 1.18em;
+ font-weight: 600;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
+ margin: 1.25em 0 0.5em 0;
+}
+
+h4 {
+ line-height: 1.18em;
+ font-size: 1em;
+ font-weight: 600;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
+ margin: 1.25em 0 0.5em 0;
+}
+
+h5, h6 {
+ font-size: 0.7em;
+ font-weight: 600;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
+ margin: 1.25em 0 0.5em 0;
+}
+
+a {
+ color: #546E00;
+ text-decoration: none;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
color: #444;
- font-family: "DejaVu Sans",Helvetica,Arial,sans-serif;
- margin: 1em 0 0.5em 0;
}
-h1, .titlearea .header .titlebox, #projectname {
- font-size: 300%;
+a:hover {
+ text-decoration: underline;
+}
+
+h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link {
+ color: #444;
+}
+
+h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited {
+ color: #444;
+}
+
+p {
+ margin: 0.5em 0 0.5em 0;
+}
+
+dt {
+ font-weight: 600;
+}
+
+dd {
+ margin-left: 2em;
+}
+
+caption {
+ font-weight: 700;
+}
+
+.title, #projectname {
+ line-height: 1.0125em;
+ margin: 0.75em 0 0 0;
+}
+
+.titlearea .header .titlebox, #projectname {
+ font-size: 1.68em;
font-weight: 400;
margin-bottom: 0.25em;
margin-top: 0;
}
+#header {
+ padding: 0 0 0.5em 0;
+ border-bottom: 1px solid #EEE;
+}
+
.header .headertitle .title {
- font-size: 180%;
- font-weight: 400;
- margin: 0.75em 0.25em 0.5em 0;
+ line-height: 1.68em;
+ font-size: 1.68em;
+ font-weight: 600;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
}
.ingroups {
- display: inline;
+ display: none;
}
+
.title .ingroups a {
font-size: small;
margin-left: 1em;
@@ -42,7 +123,8 @@ h1, .titlearea .header .titlebox, #projectname {
#titlebox, #metabox {
display: inline-block;
}
-#titlebox{
+
+#titlebox {
display: inline-block;
width: 75%;
left: 0;
@@ -51,6 +133,18 @@ h1, .titlearea .header .titlebox, #projectname {
#title {
margin-bottom: 0.25em;
+ line-height: 1.25em;
+ font-size: 2.5em;
+ color: #333;
+ font-weight: 600;
+}
+
+.PageDoc {
+ margin-top: 1.5em;
+}
+
+.PageDoc .header .headertitle .title {
+ display: none;
}
#shortdesc {
@@ -58,68 +152,24 @@ h1, .titlearea .header .titlebox, #projectname {
color: #666;
display: inline-block;
font-style: italic;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
padding: 0;
}
#titlearea {
- margin: 0.25em auto 0.25em auto;
+ margin: 0.25em auto 0 auto;
padding: 0;
position: relative;
clear: both;
- line-height: 1.0em;
-}
-
-h2 {
- font-size: 160%;
- font-weight: 400;
-}
-
-h3 {
- font-size: 140%;
- font-weight: 400;
-}
-
-h4 {
- font-size: 120%;
- font-weight: 500;
-}
-
-h5, h6 {
- font-size: 110%;
- font-weight: 600;
-}
-
-h1 a, h1 a:link, h1 a:visited ,
-h2 a, h2 a:link, h2 a:visited ,
-h3 a, h3 a:link, h3 a:visited ,
-h4 a, h4 a:link, h4 a:visited ,
-h5 a, h5 a:link, h5 a:visited ,
-h6 a, h6 a:link, h6 a:visited {
- color: #444;
-}
-
-p {
- margin: 0.5em 0 0.5em 0;
-}
-
-dt {
- font-weight: 700;
-}
-
-dd {
- margin-left: 2em;
-}
-
-caption {
- font-weight: 700;
+ line-height: 1em;
}
-span.legend {
+.legend {
font-size: small;
text-align: center;
}
-h3.version {
+.version {
font-size: small;
text-align: center;
}
@@ -136,20 +186,10 @@ div.navtab {
margin-right: 15px;
}
-/* @group Link Styling */
-a {
- color: #546E00;
- text-decoration: none;
-}
-
.contents a:visited {
color: #344E00;
}
-a:hover {
- text-decoration: underline;
-}
-
a.qindexHL {
background-color: #9CAFD4;
color: #FFF;
@@ -158,15 +198,19 @@ a.qindexHL {
code {
color: #444;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
}
-/* @end */
dl.el {
margin-left: -1cm;
}
+a.el {
+ font-family: "DejaVu Sans Mono", monospace, fixed;
+}
+
.fragment {
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
}
pre.fragment {
@@ -182,7 +226,7 @@ div.ah {
color: #FFF;
margin-bottom: 3px;
margin-top: 3px;
- padding: .2em;
+ padding: 0.2em;
border: thin solid #333;
}
@@ -203,12 +247,17 @@ div.groupText {
}
div.contents, #content {
- padding: 0 0.25em 0 0.25em;
max-width: 60em;
margin-left: auto;
margin-right: auto;
}
+.groupheader + p {
+ font-style: italic;
+ color: #666;
+ margin: 0 0 1em 0;
+}
+
td.indexkey {
background-color: #EBEFF6;
font-weight: 700;
@@ -225,7 +274,20 @@ td.indexvalue {
}
table.memname {
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
+ border-spacing: 0;
+}
+
+table.memname tbody tr:last-child {
+ display: none;
+}
+
+table.memname tbody tr:only-child {
+ display: table-cell;
+}
+
+table.memname tbody tr:nth-last-child(2)::after {
+ content: ")";
}
tr.memlist {
@@ -260,7 +322,6 @@ img.footer {
vertical-align: middle;
}
-/* @group Code Colorization */
span.keyword {
color: #586E75;
}
@@ -289,7 +350,6 @@ span.charliteral {
color: #CB4B16;
}
-/* @end */
td.tiny {
font-size: x-small;
}
@@ -309,7 +369,7 @@ hr {
height: 0;
border: none;
border-top: 1px solid #DDD;
- margin: 2em 0 1em;
+ margin: 2em 0;
}
#footer {
@@ -322,7 +382,10 @@ hr {
color: #888;
}
-/* @group Member Descriptions */
+td.ititle {
+ padding-bottom: 0.75em;
+}
+
table.memberdecls {
border-spacing: 0.125em;
line-height: 1.3em;
@@ -339,13 +402,12 @@ table.memberdecls {
.memItemLeft,.memItemRight,.memTemplParams {
border: 0;
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
}
.memItemLeft,.memTemplItemLeft {
white-space: nowrap;
padding-left: 2em;
- padding-right: 1em;
}
.memItemLeft a.el {
@@ -371,13 +433,10 @@ td.mlabels-right {
display: none;
}
-/* @end */
-/* @group Member Details */
-/* Styles for detailed member documentation */
.memtemplate {
color: #888;
font-style: italic;
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
font-size: small;
}
@@ -391,25 +450,33 @@ td.mlabels-right {
}
.memitem {
- padding: 0.25em 0.5em 0.25em 0.5em;
- margin: 0 0 1em 0;
- border-radius: 6px;
- border: 1px solid #DDD;
+ padding: 0.5em 0.5em 0.25em 0.5em;
+ margin: 1em 0 2em 0;
}
.memproto {
- font-size: 110%;
- font-weight: 400;
- line-height: 1em;
- color: #000;
+ border-bottom: 1px solid #EEE;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
+ font-size: 1.09em;
+ font-weight: 600;
+ line-height: 1.41em;
+ margin-bottom: 0.25em;
+ padding-bottom: 0.125em;
}
.memproto .paramname {
font-style: normal;
+ padding-right: 0.25em;
}
.memdoc {
- padding: 0 0.25em 0 0.25em;
+ padding: 0;
+}
+
+.memdoc > p:first-child {
+ font-style: italic;
+ color: #444;
+ margin-bottom: 0.75em;
}
.paramkey {
@@ -418,16 +485,17 @@ td.mlabels-right {
.paramtype {
color: #666;
- padding-right: 0.5em;
+ padding: 0 0.25em 0 0.25em;
white-space: nowrap;
}
-.paramname {
+.params .paramname {
color: #111;
white-space: nowrap;
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
font-style: italic;
padding-right: 0.5em;
+ vertical-align: top;
}
.fieldname {
@@ -435,8 +503,8 @@ td.mlabels-right {
}
.fieldtable {
- padding-top: 0.25em;
- border-top: 1px dashed #DDD;
+ margin-top: 0.5em;
+ border-collapse: collapse;
}
.fieldtable tbody tr:first-child {
@@ -444,21 +512,29 @@ td.mlabels-right {
}
td.fieldname {
- padding: 0 0.5em 0 0.25em;
vertical-align: top;
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
+}
+
+td.fielddoc {
+ padding: 0.125em 0.5em 0 0.25em;
+ vertical-align: top;
+}
+
+.fieldtable tbody tr td {
+ border-top: 1px dashed #DDD;
+ border-bottom: 1px dashed #DDD;
}
td.fieldtype {
color: #666;
padding: 0 0.5em 0 0;
vertical-align: top;
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
}
td.fielddoc p {
margin: 0;
- vertical-align: top;
padding: 0 0.5em 0 0;
}
@@ -467,17 +543,12 @@ p.reference {
font-style: italic;
}
-/* @end */
-/* @group Directory (tree) */
-/* for the tree view */
.ftvtree {
- font-family: sans-serif;
+ font-family: "DejaVu Sans", Verdana, Helvetica, Arial, sans-serif;
margin: 0;
}
-/* these are for tree view when used as main index */
.directory {
- font-size: small;
margin: 0.5em;
}
@@ -506,7 +577,7 @@ p.reference {
}
td.entry {
- font-family: "DejaVu Sans",Helvetica,Arial,sans-serif;
+ font-family: "DejaVu Sans", Verdana, Helvetica, Arial, sans-serif;
font-weight: 400;
padding-right: 1em;
}
@@ -522,12 +593,11 @@ td.entry {
}
td.entry b {
- font-family: "DejaVu Sans",Helvetica,Arial,sans-serif;
+ font-family: "DejaVu Sans", Verdana, Helvetica, Arial, sans-serif;
font-weight: 400;
font-size: 130%;
}
-/* these are for tree view when not used as main index */
.directory-alt {
font-size: 100%;
font-weight: bold;
@@ -557,7 +627,6 @@ td.entry b {
vertical-align: -30%;
}
-/* @end */
div.dynheader {
margin-top: 8px;
}
@@ -620,29 +689,25 @@ div.navpath {
div.summary {
font-size: small;
- font-family: "DejaVu Sans",Helvetica,Arial,sans-serif;
+ font-family: "DejaVu Sans", Verdana, Helvetica, Arial, sans-serif;
margin: 0;
- color: #FFF; /* Hide separator bars */
- border-bottom: 1px solid #DDD;
padding: 0.25em 0;
+ display: none;
}
div.summary a {
white-space: nowrap;
}
-/* Metadata box (right aligned next to title) */
-
#metabox {
display: inline-block;
font-size: x-small;
- margin: 0 0 0.25em 0;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
position: absolute;
right: 0;
- top: 0;
+ bottom: 0.25em;
color: #666;
font-style: italic;
- padding: 0 1em;
}
#meta {
@@ -661,12 +726,12 @@ div.summary a {
text-align: right;
}
-#meta th:after {
+#meta th::after {
content: ":";
}
div.line {
- font-family: "DejaVu Sans Mono",monospace,fixed;
+ font-family: "DejaVu Sans Mono", monospace, fixed;
line-height: 1.4em;
white-space: pre-wrap;
}
@@ -683,6 +748,7 @@ span.lineno {
background-color: #E8E8E8;
white-space: pre;
}
+
span.lineno a {
background-color: #D8D8D8;
}
@@ -693,9 +759,8 @@ span.lineno a:hover {
.tabs, .tabs2, .navpath {
padding: 0.25em 0;
- border-bottom: 1px solid #DDD;
font-size: small;
- font-family: "DejaVu Sans",Helvetica,Arial,sans-serif;
+ font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
margin: 0;
}
@@ -709,13 +774,11 @@ th {
padding: 0.125em;
}
-#navrow1 {
+#navrow1, #navrow2 {
/* Disable menu from Doxygen 1.8.15, it is faked in the template */
display: none;
}
-/* tabs*/
-
.tablist {
margin: 0;
padding: 0;
@@ -732,7 +795,6 @@ th {
.tablist a {
display: block;
padding: 0 1em 0 0;
- font-family: "DejaVu Sans",Helvetica,Arial,sans-serif;
text-decoration: none;
outline: none;
}
generated by cgit v1.2.1 (git 2.18.0) at 2024-12-26 17:31:27 +0000