This is new wiki software and old wiki content. It's a work in progress!
Here's the explanation.
Be gentle, report bugs, leave feedback on pages, or just edit them yourself! Thanks!

SDL Wiki

Style Guide: Structure Pages

This guide provides specific instructions for editing or adding your own content to each section of a Structure page in this wiki.

Structure pages should provide basic information about the SDL structures to allow users to most effectively utilize them in their projects.

General Guidelines

Important note about Unions
The basic structure template is also used for unions that have pages in the wiki. For simplicity, the following guidelines for structures will also apply to unions unless a specific difference is noted.

Please observe the following for all structure pages:

```||<tablewidth="100%" #000000 style="color: #FF8C00;" :>
~+For Backward Compatibility Only+~

||```

~-Return to Table of Contents-~

== Getting Started ==

1. Begin by going to the page you wish to edit and selecting Edit (Text) or Edit (GUI) in the left column to begin editing.
 {i} ~-Markup info provided here is specifically for use in the Text editor but should work in both.-~
1. Scroll down in the edit window to the section(s) you want to edit.  Add your content following the conventions in this style guide.
1. Find information relevant to your content in the style guide sections below and apply the appropriate formatting as you edit.
1. Preview your work as you go by clicking Preview in the left column.  Preview often and any time you are unsure of formatting. 

~-(Keep in mind that a few things (like Color2 text) don't preview exactly as they parse.)-~

1. Save your work by clicking Save Changes in the left column after you are satisfied with your content and have filled in the Comment field under the editing box. 

For assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>>.

~-Return to Table of Contents-~

Editing Specific Sections

Title

Do not edit the Title.

The Title section consists of the page heading and its markup:

```= SDL_StructureName =``` 

For structure pages this is the name of the structure being described on the page and should match the address of the page.

Example: The page address ```https://wiki.libsdl.org/SDL_PixelFormat``` should have matching title and describe the SDL_PixelFormat structure.

If you believe a change is necessary please submit Feedback from that page or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>>.

~-Return to Table of Contents-~

=== Description === The Description section immediately follows the page title and does not have it's own heading.

'''Structure descriptions begin with:

```A structure that contains```'''
 or very rarely
```A union that contains```

followed by a clear and concise description of what the structure contains.

Note: Information presented in this section is meant to be limited. Extended description information for more complicated structures should be placed in the Remarks section instead.

Note: Exceptions to the basic description are very unusual. Follow established patterns in the wiki (based on similar pages which may be found by text search) whenever possible if an exception seems appropriate.

<( |2 30%>If the page describes __a union__ rather than a structure

Action: Use the alternate description (A union that contains...) and, if necessary, replace the word structure with the word union where appropriate throughout the page.

Example: SDL_Event

<( |2 30%>If __another API page__ is referenced in the description

Action: Be sure to hyperlink it and use () outside the link markup if it is a function.

Example: ```SDL_FunctionName(), SDL_StructureName```, SDL_GetThreadName()

<( |4 30%>If __a data field on that page__ is referenced in the description

Action: Use bold for the field name.

Note: This is a very rare occurrence.

Note: If the reference is to the data field as a concept (ie: the refresh rate) rather than directly to the parameter itself (ie: refresh_rate) do not make it bold.
~-Please don't just make the word bold every time it occurs on the page.-~

Example: SDL_LoadWAV_RW(), SDL_DisplayMode, SDL_Surface

~-Return to Table of Contents-~

=== Table of Contents === Do not edit the Table of Contents.

The Table of Contents consists of the following markup and is generated automatically on the parsed page.

```<<TableOfContents()>>```

If you believe a change is necessary please submit Feedback from that page or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>>.

~-Return to Table of Contents-~

=== Data Fields === The Data Fields section provides basic information about each field in the structure and is presented in table format.

The basic format is as follows: ``` ||type1||field1||description|| ||type2*||field2||description|| ||type3||field3||description|| ... ||typeN||fieldN||description|| ```

Markup: Use basic table markup and enclose each field name in bold markup. All text in the table is left-justified.

Important! All descriptions begin with a lower case letter, end without a period, and are generally not complete sentences.

Example: SDL_Surface, SDL_JoyButtonEvent, SDL_Palette, SDL_HapticCondition

Action: There are a few content-dependent conventions we have chosen for consistency across pages. See the tables below for details.

<bgcolor="#EDEDED">General (whole table)

<( |4 30%>If the field is __for internal use, deprecated, or unused__ (greyed out)

Action 1: Place a text notation in parentheses at the end of the description (ie: (deprecated))

Action 2: Make the text in the row grey by including the following, verbatim, in the first cell of the row between the starting table markup and the text:
```<rowstyle="color: #808080;">```

Note: Although a rare case, any other style markup for that row/cell should be included within the same set of angle brackets (<>) and separated from this markup by a space.

Example: ```

<rowstyle="color: #808080;">type

<( |3 30%>If the field is __read-only__

Action: Place the text notation (read-only) in parentheses at the end of the description.
Do not grey out the line.
If all fields are read-only notate it in the Remarks instead.

Note: This also applies to the rare "(read-write)" field.

Example: SDL_Surface, SDL_PixelFormat

<( |3 30%>If __another API page__ is referenced and __the field is greyed out__ (see above)

Action 1: DO NOT hyperlink the page in the type column.

Action 2: List the page, with a hyperlink, in the description, Remarks, and/or in the appropriate "Related" section at the bottom of the page, if appropriate.

Example: SDL_Event

<( |3 30%>If __another API page__ is referenced and __the field is not greyed out__ (see above)

Action1: Be sure to hyperlink it and use () outside the link markup if it is a function.

Action 2: List the page in the appropriate "Related" section at the bottom of the page, if appropriate.

Example: SDL_Event, SDL_AudioSpec, SDL_SysWMinfo

<( |4 30%>If there are __important, distinct groups of fields__ within the structure

Action: Create sections by placing a full-width row with a grey background and centered, italics title above each group.

Markup: Begin the row with empty table cells equal to the number of columns in the table -1 (ie: 2 empty cells for a 3 column table). Place the following markup in the next cell
<bgcolor="#EDEDED">Section Title
Replace Section Title with appropriate text and close the last column.

Note: This is a rare occurrence. Do not use sections unless they significantly improve the meaning, clarity, or usability of the information.

Example: this table, SDL_HapticConstant, SDL_HapticRamp

<( |2 30%>If the structure includes __padding__ fields

Action: Omit all padding fields from the wiki page.

Example: SDL_AudioSpec, SDL_WindowEvent

<( |3 30%>If there is __a pointer__ associated with the field

Action 1: Place the pointer symbol(s) at the end of the type in the first column with no space between.

Action 2: In general, avoid mentioning the pointer in the description unless it is necessary to understand the field.

Example: ```

type*

<bgcolor="#EDEDED">First Column (type) & Second Column (field)

<(>There are currently no special formatting instructions that affect only these columns. See General above.

<bgcolor="#EDEDED">Third Column (description)

<( |3 30%>If __more than one statement__ must be included in the description

Action: Separate them with a semi-colon (;)

Note: This should be avoided whenever possible. See "If a __more detailed description__ is required to adequately explain a field" below for more details.

Example: SDL_JoyButtonEvent, SDL_Keysym

<( |4 30%>If a __more detailed description__ is required to adequately explain a field

Action 1 : Append the following, verbatim, to the end of the brief description
```; see Remarks for details```

Action 2: Place the more detailed information in the Remarks section.

Action 3: See "If the __Remarks section is large__" below for more details.

Example: SDL_RendererInfo, SDL_HapticEffect

<( |4 30%>If the __Remarks section is large__

Action 1: Create an anchor immediately before the additional comments you are adding to the Remarks section.

Markup: Use ``````, where anchorname is a name of your choosing, to create the anchor in the Remarks section. See Anchors for details.

Action 2: Modify the Remarks link in the parameter description (see Action 1 in "If a __more detailed description__ is required to adequately explain a field" above) to the following:
```; see Remarks for details```
where anchorname matches the name you chose for the anchor in Action 1.

Example: SDL_RendererInfo

<( |4 30%>If __a field references another field__ on that same page

Action: Use bold for the field name.

Note: This is a very rare occurrence.

Note: If the reference is to the field as a concept rather than directly to the field itself do not make it bold.
~-Please don't just make the word bold every time it occurs on the page.-~

Example: SDL_AudioCVT, SDL_HapticCustom

<( |2 30%>If there is __no relevant description text__

Action: It is acceptable to leave the description cell blank, although it is preferable to put some information there even if it is redundant with the field name or otherwise does not really provide any novel information.

Example: SDL_Color

~-Return to Table of Contents-~

=== Code Examples === The Code Examples section is meant to contain simple, meaningful examples of how to use the structure in a program.

This is one of the few sections that is intended to grow and adjust as users discover more information about a structure that would be helpful to share with other users.

For the most part the contents of the Code Examples section will be user-generated and this section will remain as-is until users input their examples.

Please see the Code Examples Style Guide for details on editing this section.

~-Return to Table of Contents-~

=== Remarks === The Remarks section is meant to contain additional information that did not fit in the other sections as well as comments regarding the behavior and use of the structure in real-world applications.

This is one of the few sections that is intended to grow and adjust as users discover more information about how a structure behaves under different circumstances.

For the most part the contents of the Remarks section will be user-generated and this section will remain as-is until users input their comments.

Note: This is __not__ an appropriate place to post questions, suggestions, bugs, or commentary. Please use the other communication channels available to you, especially the forums and Feedback form, for these types of remarks.

Please see the Remarks Style Guide for details on editing this section.

~-Return to Table of Contents-~

=== Related Enumerations === The Related Enumerations section provides a list of enumerations specifically referenced by the structure or otherwise closely related to it.

This list __should__ include:

~-(ie: the enum is not a field type but its values are used to fill in a field as with SDL_EventType for the type field in many event structures)-~

This list __should not__ include:

~-Including too many would make these lists much less valuable.-~
~-(ie: it might be common to use them together)-~
~-(ie: do not include functions or structures in this list)-~

Markup: Each line should begin with a single blank space and a period followed by the enumeration name enclosed in double brackets to create a hyperlink.

Note: Do not include empty parentheses after the name.
The basic format for the Related Enumerations list is:

```

.SDL_EnumerationName
.SDL_EnumerationName

```

~-Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.-~

<( 30%>If there is __more than one enumeration__ in the list

Action: List the enumerations in alphabetical order.

<( 30%>If the structure is __a member of the SDL_Event union__

Action: Include SDL_EventType in this section of the page.

<( |2 30%>If there are __no related enumerations__

Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant.

Note: It is common for this section to be empty and removed from the page.

Example: SDL_Event, SDL_Keysym, SDL_WindowEvent

~-Return to Table of Contents-~

=== Related Structures === The Related Structures section provides a list of other structures (or unions) specifically referenced by the structure or otherwise closely related to it.

This list __should__ include:

~-This is uncommon.-~

This list __should not__ include:

~-Including too many would make these lists much less valuable.-~
~-(ie: it might be common to use them together)-~
~-(ie: do not include functions or enumerations in this list)-~

Markup: Each line should begin with a single blank space and a period followed by the structure name enclosed in double brackets to create a hyperlink.

Note: Do not include empty parentheses after the name.
The basic format for the Related Structures list is:

```

.SDL_StructureName
.SDL_StructureName

```

~-Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.-~

<( 30%>If there is __more than one structure__ in the list

Action: List the structures in alphabetical order.

<( 30%>If the structure is __a member of the SDL_Event union__

Action: Include SDL_Event in this section of the page.

<( |2 30%>If there are __no related structures__

Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant.

Note: It is common for this section to be empty and removed from the page.

Example: SDL_Event, SDL_Color, SDL_HapticDirection

~-Return to Table of Contents-~

{i} This is a custom section that should not be used except in the most specific circumstances. Example: SDL_version The Related Macros section provides a list of functions specifically associated with that structure or otherwise closely related to it.

~-Return to Table of Contents-~

The Related Functions section provides a list of functions specifically associated with that structure or otherwise closely related to it.

This list __should__ include:

This list __should not__ include:

~-Including too many would make these lists much less valuable.-~

Markup: Each line should begin with a single blank space and a period followed by the function name enclosed in double brackets to create a hyperlink.

Note: Do not include empty parentheses after the function names in this section. They are all functions so it should be understood/unnecessary.
The basic format for the Related Functions list is:

```

.SDL_FunctionName
.SDL_FunctionName

```

~-Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.-~

<( 30%>If there is __more than one function__ in the list

Action: List the functions in alphabetical order.

<( 30%>If there are __no related functions__

Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant.

Example: SDL_TextInputEvent, SDL_SysWMinfo

~-Return to Table of Contents-~

The Footer section consists of a horizontal rule followed by two links separated by a comma.

Markup: ```


CategoryStruct, CategoryHeader ```

where CategoryStruct is the same for every structure page and CategoryHeader is structure-specific with Header varying based on the header file containing the structure (see below).

Important! Category names do not always match the header file name. Please consult the following table for the correct name to use so the structure will appear in the correct list(s).

Action 1: Do not edit the CategoryStruct link!

Action 2: The ```CategoryHeader``` link may be edited if the page still says (as on a new page) or if the structure has been relocated to another header (very rare).

Important! There are a few exceptions to this rule (pages with a category name that does not match their header file). These have been determined by the SDL team. Please do not change an existing page's category name simply because it does not match its header file. If you are concerned that a name is incorrect please submit Feedback from that page or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>> to confirm the change first.

Markup: Replace CategoryHeader with the appropriate category name from the table that follows, or contact us at <<MailTo(ANTI SPAM wiki AT libsdl DOT org)>> to find out what category name to use if you are unsure or if the category appears to be missing.

<rowbgcolor="#EDEDED">Header File Containing the Structure*

Corresponding Category Name

SDL.h

CategoryInit

SDL_assert.h

CategoryAssertions

SDL_atomic.h

CategoryAtomic

SDL_audio.h

CategoryAudio

SDL_clipboard.h

CategoryClipboard

SDL_compat.h

CategoryCompat

SDL_cpuinfo.h

CategoryCPU

SDL_endian.h

CategoryEndian

SDL_error.h

CategoryError

SDL_events.h

CategoryEvents

SDL_haptic.h

CategoryForceFeedback

SDL_hints.h

CategoryHints

SDL_joystick.h

CategoryJoystick

SDL_keyboard.h

CategoryKeyboard

SDL_keycode.h

CategoryKeyboard

SDL_loadso.h

CategorySharedObject

SDL_log.h

CategoryLog

SDL_mouse.h

CategoryMouse

SDL_mutex.h

CategoryMutex

SDL_pixels.h

CategoryPixels

SDL_platform.h

CategoryPlatform

SDL_power.h

CategoryPower

SDL_quit.h

CategoryEvents

SDL_rect.h

CategoryRect

SDL_render.h

CategoryRender

SDL_rwops.h

CategoryIO

SDL_scancode.h

CategoryKeyboard

SDL_surface.h

CategorySurface

SDL_syswm.h

CategorySWM

SDL_thread.h

CategoryThread

SDL_timer.h

CategoryTimer

SDL_version.h

CategoryVersion

SDL_video.h

CategoryVideo

~-*Some exceptions exist. See above.-~

~-Return to Table of Contents-~

Special

This section contains details for special formatting circumstances that are best described separately from the average structure page. In general these guidelines should be used in conjunction with the above.

Callback Functions

Although having a callback function associated with a structure is rare, it does occasionally occur. Documenting this will affect two (2) sections of the structure's page - Data Fields and Remarks.

Note: Because callback functions are so rare with structures most of the examples listed here will be on function pages. This is for illustrative purposes only. As of this writing the only callback associated with a structure is the audio callback, found with SDL_AudioSpec. Because of this rarity many of the guidelines below will not currently apply to a structure-based callback, but this is being written with the future possibilities in mind.

Action 1: Use the following formatting specifics in addition to those listed above for the structure whenever a callback function is included on a structure page:

<bgcolor="#EDEDED">Data Fields Section Formatting Details

<( |3 30%>For the field that refers to the __callback__ function

Action: Use the following wording, modified as necessary, to describe the field:
the function to call <when/why>; see Remarks for details
where the text in <> is replaced with an appropriate description of when or why the callback would be called.

Note: This parameter is often named callback but may have other names.

Example: SDL_LogSetOutputFunction(), SDL_AddEventWatch(), SDL_CreateThread(), SDL_SetAssertionHandler()

<( |4 30%>For the field that passes __user data__ to the callback

Action: Use the following wording, modified as necessary, to describe the field:
a pointer that is passed to callback
where callback is replaced with the callback function field name (if necessary).

Note: In rare cases this may be a pointer to a pointer and should be described as such.

Note: This field is often named userdata, but may have other names. It is important to distinguish this field from other fields that are passed to the callback also, but that are not strictly carrying "user data", and from other fields that are unrelated to the callback function (such as samples, channels). See below for details.

Example: SDL_AudioSpec, SDL_LogSetOutputFunction(), SDL_CreateThread()

<( |2 30%>For other fields __related to the callback__

Action: There may be other fields that are passed to the callback function but which are sufficiently different from the __user data__ concept that the wording above does not really apply. In these cases use a description that is appropriate. Often it will still be appropriate to include the phrase passed to callback in these descriptions.

Example: SDL_AddTimer()

<( |2 30%>For additional data fields __not related to the callback__

Action: Follow any applicable guidelines listed above

Example: SDL_CreateThread()

Action 2: Detail the syntax and parameters of the callback function in the Remarks section using the following __basic format__ with the changes listed in the table below:

  ```{

The function prototype for callback is:

}

to display

The function prototype for callback is:

callback syntax
where its parameters are:

||callback parameter||description||

optional return value info...
optional remarks or details...

<bgcolor="#EDEDED">Remarks Section Formatting Details

<( |2 30%>__Location__

Action: Generally the Remarks section is roughly organized in the same order as the data fields. Callback details should be located in the appropriate region of the Remarks section or at the top if all other Remarks are less directly related to a particular data field. But, logic should prevail in determining where to place this information if the Remarks section is large. The callback information should be prominent.

Example: SDL_CreateThread(), SDL_AddEventWatch(), SDL_SetAssertionHandler()

<( 30%>__Alignment__

Action: As shown in the basic format above, only the first line should be left-justified. Everything else related directly to the callback should be indented one level (or more) to indicate it's relationship to the callback as opposed to the structure.

<( |2 30%>If the callback field is __not callback__

Action: Replace callback in the basic format above with the data field name used in the structure to refer to the callback function.

Example: SDL_SetEventFilter(), SDL_CreateThread(), SDL_SetAssertionHandler()

<( 30%>For __"callback syntax"__ in the basic format above

Action: Replace "callback syntax" with the callback function's syntax formatted the same as regular functions.

<( |2 30%>If the __callback function name__ requires any explanation

Action: Replace "where its parameters are:" in the basic format above with the following:
where is <some explanation> and its parameters are:
replacing with the name of the callback function and <some explanation> with an explanation of the name (ie: your function name).

Example: SDL_AddEventWatch()

<( |4 30%>For __| callback parameter | description |__ in the basic format above

Action 1: Duplicate the line from above for each parameter in the callback (ie: there should be 2 lines for 2 parameters).

Action 2: Replace "callback parameter" with the name of each callback function parameter using the same formatting instructions as regular functions except use ```monospace``` (surrounding backticks) rather than bold to highlight the parameter names in the first column.

Action 3: Replace "description" with an appropriate description of the callback's parameter. See the following for specific parameters.

Example: SDL_FilterEvents(), SDL_LogSetOutputFunction()

<( |2 30%>For the __userdata__ parameter (or comparable)

Action: Use the following text (modified as necessary):
an application-specific parameter saved as userdata in SDL_StructureName()
replacing userdata with the appropriate parameter name if necessary, and replacing StructureName with the name of the structure on the page.

Example: SDL_AddEventWatch(), SDL_AddTimer()

<( |3 30%>If the callback function's __return value__ is important

Action 1: Replace "optional return value info..." in the basic format above with the relevant return value information. Be sure to indent text one level as shown.

Note: Callback return value information may be omitted if it is not important. It may be left-justified if it is discussed in the context of the structure rather than the callback itself.

Example: SDL_AudioSpec, SDL_AddEventWatch(), SDL_AddTimer()

<( |2 30%>If there are __"optional remarks or details"__

Action: Replace "optional remarks or details..." in the basic format above with any other relevant information about the callback function. Be sure to indent text at least one level as shown.

Example: SDL_LogGetOutputFunction(), SDL_LogSetOutputFunction()


Compatibility Structures

Compatibility Structures are present in the API for backward compatibility only and thus are treated slightly differently than structures from the current version. Use the following formatting specifics in addition to those listed above for all CategoryCompat pages::

Action 1: The top of every compatibility structure page should include the following, verbatim, to be placed below the pragma markup, below DRAFT if present, and above the page title:

```

||<tablewidth="100%" #000000 style="color: #FF8C00;" :> <
>~+For Backward Compatibility Only+~<
><
> || ```

Action 2:

||<( 30%>If __only one SDL 1.3 structure__ replaces the compatibility structure||Action: See Markup A below.||
||<( |2 30%>If __more than one SDL 1.3 structure__ has replaced the compatibility structure||Action: See Markup B below.||
||Note: This should occur only very rarely, if at all.  Please avoid making the list any larger than necessary.  This is NOT a related structures list!||
||<( 30%>If there are __no equivalent structures__ in SDL 1.3||Action: See Markup C below.||
||||ExampleSDL_ActiveEventSDL_OverlaySDL_VideoInfo||


: Markup A: Add the following section to the end of the page above the footer. Replace SDL_Structure with the name of the appropriate SDL 1.3 structure:

 ```

SDL 1.3 Replacement(s)

||<tablewidth="100%" #000000 style="color: #FF8C00;">This structure has been replaced by the following in SDL 1.3: SDL_Structure|| ```
: Markup B: Add the following section to the end of the page above the footer. Create a list of structures by repeating the SDL_Structure markup, separating each member of the list with a comma, and placing the most direct counterpart first, alphabetizing any additional structures after that.

 ```

SDL 1.3 Replacement(s)

||<tablewidth="100%" #000000 style="color: #FF8C00;">This structure has been replaced by the following in SDL 1.3: SDL_Structure, SDL_Structure|| ```
: Markup C: Add the following section to the end of the page above the footer. Replace Other options here with text describing other options in SDL 1.3 that could be used to accomplish the same goal, or remove it if there is no applicable text:

 ```

SDL 1.3 Replacement(s)

||<tablewidth="100%" #000000 style="color: #FF8C00;">There are currently no equivalent structures in SDL 1.3.|| Other options here ```

Example: See other CategoryCompat pages for examples

~-Return to Table of Contents-~

<<Include(SGWikiBasics, , , from="Start SG Include here.", to="##End SG Include here.")>>


[ edit | delete | history | feedback | raw ]

[ front page | index | search | recent changes | git repo | offline html ]

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.