From 1b3b338f5db67449e868ddfaf9e5751c131925be Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 7 Mar 2020 18:28:44 +0100 Subject: Improve documentation style and rewrite main page --- doc/header.html | 2 + doc/layout.xml | 2 +- doc/mainpage.md | 60 ++++++--- doc/reference.doxygen.in | 6 +- doc/style.css | 322 ++++++++++++++++++++++++++++------------------- 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 @@ 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 @@ + @@ -93,7 +94,6 @@ - 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; } -- cgit v1.2.1