From 02a622db9541bb57736d5b217510f996fc71ca64 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Wed, 8 May 2024 20:46:52 -0400 Subject: [PATCH] SDL2: Removed a bunch of MoinMoin cruft and outdated Style Guide stuff. --- SDL2/Contributing.mediawiki | 83 -- SDL2/SDLEnumTemplate.mediawiki | 45 - SDL2/SDLFunctionTemplate.mediawiki | 53 - SDL2/SDLStructTemplate.mediawiki | 51 - SDL2/SDL_Colour.mediawiki | 6 +- SDL2/SDL_Finger.mediawiki | 8 - SDL2/SDL_GameControllerBindType.mediawiki | 8 - SDL2/SDL_GetEventState.mediawiki | 9 - ...ANDROID_SEPARATE_MOUSE_AND_TOUCH.mediawiki | 9 - ...DL_HINT_WINRT_HANDLE_BACK_BUTTON.mediawiki | 8 - ..._HINT_WINRT_PRIVACY_POLICY_LABEL.mediawiki | 8 - SDL2/SDL_JoystickPowerLevel.mediawiki | 8 - SDL2/SDL_MessageBoxColorType.mediawiki | 8 - SDL2/SDL_assert_data.mediawiki | 2 - SDL2/SDL_iOSSetAnimationCallback.mediawiki | 1 - SDL2/SDL_iOSSetEventPump.mediawiki | 1 - SDL2/SGEnumerations.mediawiki | 594 ----------- SDL2/SGFunctions.mediawiki | 942 ------------------ SDL2/SGNewPages.mediawiki | 97 -- SDL2/SGRemarks.mediawiki | 181 ---- SDL2/SGStructures.mediawiki | 775 -------------- SDL2/SGTutorials.mediawiki | 151 --- SDL2/SGWikiBasics.mediawiki | 807 --------------- 23 files changed, 5 insertions(+), 3850 deletions(-) delete mode 100644 SDL2/Contributing.mediawiki delete mode 100644 SDL2/SDLEnumTemplate.mediawiki delete mode 100644 SDL2/SDLFunctionTemplate.mediawiki delete mode 100644 SDL2/SDLStructTemplate.mediawiki delete mode 100644 SDL2/SDL_iOSSetAnimationCallback.mediawiki delete mode 100644 SDL2/SDL_iOSSetEventPump.mediawiki delete mode 100644 SDL2/SGEnumerations.mediawiki delete mode 100644 SDL2/SGFunctions.mediawiki delete mode 100644 SDL2/SGNewPages.mediawiki delete mode 100644 SDL2/SGRemarks.mediawiki delete mode 100644 SDL2/SGStructures.mediawiki delete mode 100644 SDL2/SGTutorials.mediawiki delete mode 100644 SDL2/SGWikiBasics.mediawiki diff --git a/SDL2/Contributing.mediawiki b/SDL2/Contributing.mediawiki deleted file mode 100644 index f5b3fe1f9..000000000 --- a/SDL2/Contributing.mediawiki +++ /dev/null @@ -1,83 +0,0 @@ -= work in progress = - -This page is leftover from the old wiki and needs to be rewritten and reformatted for the new wiki. Among other things: the anti-spam thing isn't true anymore. Just click "edit" on any page and we authenticate you automatically through GitHub now. - -= old wiki contents follows = - - - -```#!wiki important -Due to spammers, write access to this wiki is disabled by default. If you haven't already, please email your wiki username and the kind(s) of edits you would like to make to <> to be given write access and to coordinate efforts. - -Thank you! -``` - -= Contributing = - -We are very pleased that you are interested in contributing! - -Our goal is to create the best documentation for SDL possible. To this end we have adopted the following guiding principles and would appreciate your keeping them in mind as you create your contributions. -: This wiki should: -* have a consistent look and feel throughout -* be easy to use -* be accurate -* contain high quality information -* be as simple and straight forward as possible - -To help you with this we have created a series of resources: - - -=== Feedback Form === -: This is the quickest and simplest way for anyone to contribute to the wiki! There is no sign up and no permissions are required to use this option. Every page of the wiki contains a drop down ''Feedback'' form (upper right) where you can post quick content ideas, questions, suggestions, etc. Simply click the form tab, fill in the text field with your contribution, include your contact information if you would like a reply, and click ''Submit''. We'll take it from there! - - -=== Mailing List === -: The [http://lists.libsdl.org/listinfo.cgi/docs-libsdl.org Documentation Mailing List] has been set up to allow users to share documentation-related topics. (There is a separate mailing list for development-related topics.) Anything from conventions to needed content, questions or comments, can be posted to the Mailing List. Plus, keep up with what others are saying and doing on the wiki. - -: We encourage all contributors to join the mailing list and participate in the discussions there. It is a great place to discuss areas that need contributions and to let others know what you are working on or if you are able to help address a request. - - -=== Style Guides by Topic === -: These are the core of our contribution resources. There is a style guide for each type of contribution you may wish to make as well as the [[SGWikiBasics|Wiki Basics]] guide which contains global information that all contributors should have. - -: '''We recommend that you begin with [[SGWikiBasics|Wiki Basics]] and then dive into the topic-specific guides that interest you before you begin to edit.''' Please check back periodically for reminders and updates! - -{| -|'''Style Guide''' -|'''Topics Covered''' -|- -|[[SGWikiBasics|Wiki Basics]] -|Starting to edit
Saving changes
Style Guide basics
Quick reference for wiki markup used in this wiki
Miscellaneous notes -|- -|[[SGCodeExamples|Code Examples]] -|Adding Code Examples to any [[SGWikiBasics#api|API page]] -|- -|[[SGRemarks|Remarks]] -|Adding Remarks to any [[SGWikiBasics#api|API page]] -|- -|[[SGTutorials|Tutorials]] -|Adding an existing tutorial to the Tutorials page
Creating a new tutorial within the wiki -|- -|[[SGFunctions|Function Pages]] -|Editing Function pages
Editing Macro pages
~-This is supplemental to the Code Examples and Remarks Style Guides-~ -|- -|[[SGStructures|Structure Pages]] -|Editing Structure pages
Editing Union pages
~-This is supplemental to the Code Examples and Remarks Style Guides-~ -|- -|[[SGEnumerations|Enumeration Pages]] -|Editing Enumeration pages
Editing Hint pages
~-This is supplemental to the Code Examples and Remarks Style Guides-~ -|- -|[[SGNewPages|New Pages]] -|Creating new pages in the wiki
~-This is supplemental to the other Style Guides-~ -|} - -: If you find something that is not addressed or is unclear in a style guide please post your questions to the Documentation mailing list, on a Forum, or email us at <>. - - -=== Email === -: For anything that is not addressed in the above you can always send an email to <>. - -== Disclaimer == -```#!wiki note -All content modifications are subject to review for consistency and quality. We reserve the right to remove or modify any content added to this wiki at any time. You may direct questions or concerns to <>. -``` diff --git a/SDL2/SDLEnumTemplate.mediawiki b/SDL2/SDLEnumTemplate.mediawiki deleted file mode 100644 index fbcf3964e..000000000 --- a/SDL2/SDLEnumTemplate.mediawiki +++ /dev/null @@ -1,45 +0,0 @@ - -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - - -= SDL_Enumeration = -An enumeration of ******. - - - - - - -== Values == -{| -|value -|description -|- -|value -|description -|- -|value -|description -|} - - - - - -== Related Structures == -:[[SDL_Structure]] - - -== Related Functions == -:[[SDL_Function]] - - ----- -[[CategoryEnum]], [[CategoryHeader]] - diff --git a/SDL2/SDLFunctionTemplate.mediawiki b/SDL2/SDLFunctionTemplate.mediawiki deleted file mode 100644 index a508d5696..000000000 --- a/SDL2/SDLFunctionTemplate.mediawiki +++ /dev/null @@ -1,53 +0,0 @@ - -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - - -= SDL_Function = -Use this function to ******. - - - - - - -== Syntax == - -value SDL_FunctionName(param) - - - - - -== Function Parameters == -{| -|'''param''' -|description -|} - - - - -== Return Value == -Returns ......; call [[SDL_GetError]]() for more information. - - - - - - -== Version == -This function is available in SDL 2.X.Y - -== Related Functions == -:[[SDL_OtherFunction]] - - ----- -[[CategoryAPI]], [[CategoryHeader]] - diff --git a/SDL2/SDLStructTemplate.mediawiki b/SDL2/SDLStructTemplate.mediawiki deleted file mode 100644 index a86d6e8ee..000000000 --- a/SDL2/SDLStructTemplate.mediawiki +++ /dev/null @@ -1,51 +0,0 @@ - -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - - -= SDL_Structure = -A structure that contains ****** - - - - - -== Data Fields == -{| -|type -|'''field''' -|description -|- -|type -|'''field''' -|description -|- -|type -|'''field''' -|description -|} - - - - - -== Related Enumerations == -:[[SDL_Enumeration]] - - -== Related Structures == -:[[SDL_Structure]] - - -== Related Functions == -:[[SDL_Function]] - - ----- -[[CategoryStruct]], [[CategoryHeader]] - diff --git a/SDL2/SDL_Colour.mediawiki b/SDL2/SDL_Colour.mediawiki index 5b7ee6e27..771eee94a 100644 --- a/SDL2/SDL_Colour.mediawiki +++ b/SDL2/SDL_Colour.mediawiki @@ -1 +1,5 @@ - +# SDL_Colour + +Please refer to [[SDL_Color]]. + + diff --git a/SDL2/SDL_Finger.mediawiki b/SDL2/SDL_Finger.mediawiki index 2c32216ae..8da7d0c0f 100644 --- a/SDL2/SDL_Finger.mediawiki +++ b/SDL2/SDL_Finger.mediawiki @@ -1,11 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - = SDL_Finger = A structure that contains touch information. diff --git a/SDL2/SDL_GameControllerBindType.mediawiki b/SDL2/SDL_GameControllerBindType.mediawiki index b745d7d93..fd5b19511 100644 --- a/SDL2/SDL_GameControllerBindType.mediawiki +++ b/SDL2/SDL_GameControllerBindType.mediawiki @@ -1,11 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - = SDL_GameControllerBindType = An enumeration of the different kinds of SDL_Joystick controls a [[SDL_GameControllerButtonBind]] can map to. diff --git a/SDL2/SDL_GetEventState.mediawiki b/SDL2/SDL_GetEventState.mediawiki index 1e9185737..bea24e913 100644 --- a/SDL2/SDL_GetEventState.mediawiki +++ b/SDL2/SDL_GetEventState.mediawiki @@ -1,12 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - - = SDL_GetEventState = Use this macro to query the current processing state of a specified [[SDL_EventType]]. diff --git a/SDL2/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH.mediawiki b/SDL2/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH.mediawiki index cf105609d..da620b2d8 100644 --- a/SDL2/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH.mediawiki +++ b/SDL2/SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH.mediawiki @@ -1,12 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - - = SDL_HINT_ANDROID_SEPARATE_MOUSE_AND_TOUCH = A hint that specifies a variable to control whether mouse and touch events are to be treated together or separately. diff --git a/SDL2/SDL_HINT_WINRT_HANDLE_BACK_BUTTON.mediawiki b/SDL2/SDL_HINT_WINRT_HANDLE_BACK_BUTTON.mediawiki index bcf27ad6b..03f941430 100644 --- a/SDL2/SDL_HINT_WINRT_HANDLE_BACK_BUTTON.mediawiki +++ b/SDL2/SDL_HINT_WINRT_HANDLE_BACK_BUTTON.mediawiki @@ -1,11 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - = SDL_HINT_WINRT_HANDLE_BACK_BUTTON = A hint that specifies a variable to allow back-button-press events on Windows Phone to be marked as handled. diff --git a/SDL2/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.mediawiki b/SDL2/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.mediawiki index 6b9f71db3..8c173c229 100644 --- a/SDL2/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.mediawiki +++ b/SDL2/SDL_HINT_WINRT_PRIVACY_POLICY_LABEL.mediawiki @@ -1,11 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - = SDL_HINT_WINRT_PRIVACY_POLICY_LABEL = A hint that specifies a label text for a WinRT app's privacy policy link. diff --git a/SDL2/SDL_JoystickPowerLevel.mediawiki b/SDL2/SDL_JoystickPowerLevel.mediawiki index 728dda664..df6a60c5f 100644 --- a/SDL2/SDL_JoystickPowerLevel.mediawiki +++ b/SDL2/SDL_JoystickPowerLevel.mediawiki @@ -1,11 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - = SDL_JoystickPowerLevel = An enumeration of battery levels of a joystick. diff --git a/SDL2/SDL_MessageBoxColorType.mediawiki b/SDL2/SDL_MessageBoxColorType.mediawiki index 7da743029..c0c831892 100644 --- a/SDL2/SDL_MessageBoxColorType.mediawiki +++ b/SDL2/SDL_MessageBoxColorType.mediawiki @@ -1,11 +1,3 @@ -== Draft == - -'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it! - - - - - = SDL_MessageBoxColorType = An enumeration of positions inside the colors array of [[SDL_MessageBoxColorScheme]]. diff --git a/SDL2/SDL_assert_data.mediawiki b/SDL2/SDL_assert_data.mediawiki index 653de6234..9c5f182b5 100644 --- a/SDL2/SDL_assert_data.mediawiki +++ b/SDL2/SDL_assert_data.mediawiki @@ -1,5 +1,3 @@ - - = SDL_assert_data = A structure that contains information about an assertion. diff --git a/SDL2/SDL_iOSSetAnimationCallback.mediawiki b/SDL2/SDL_iOSSetAnimationCallback.mediawiki deleted file mode 100644 index 7cf9a7475..000000000 --- a/SDL2/SDL_iOSSetAnimationCallback.mediawiki +++ /dev/null @@ -1 +0,0 @@ - diff --git a/SDL2/SDL_iOSSetEventPump.mediawiki b/SDL2/SDL_iOSSetEventPump.mediawiki deleted file mode 100644 index f95c6d44c..000000000 --- a/SDL2/SDL_iOSSetEventPump.mediawiki +++ /dev/null @@ -1 +0,0 @@ - diff --git a/SDL2/SGEnumerations.mediawiki b/SDL2/SGEnumerations.mediawiki deleted file mode 100644 index 46f712341..000000000 --- a/SDL2/SGEnumerations.mediawiki +++ /dev/null @@ -1,594 +0,0 @@ - - -= Style Guide: Enumerations Pages = -This guide provides specific instructions for editing or adding your own content to each section of an Enumeration page in this wiki. - -'''Enumeration pages should provide basic information about the SDL enumerations to allow users to most effectively utilize them in their projects.''' - - - - -== General Guidelines == -{| -|Important note about '''Hints'''
The basic enumeration template is also used for hints that have pages in the wiki. For simplicity, the following guidelines for enumerations will also apply to hints unless a specific difference is noted. -|} - -'''Please observe the following for all enumeration pages:''' -* Do not post anything that you do not have permission to post publicly. - -* Sections should have adequate details to make them clear and useful while remaining brief wherever possible. Code Examples and Remarks may be more extensive than other sections if necessary. - -* Please remember to keep it accurate, simple, and easy to understand. - -* Do not remove, modify, or add to the markup above the page title ~-(processing instructions (ie: #pragma, #acl), DRAFT markup, etc.)-~ except: -* On CategoryCompat pages, place the following markup above the page title and below the processing instructions or DRAFT markup, if present: -: ```||
~+For Backward Compatibility Only+~

||``` - -* Do not remove, modify, or add section headings unless specifically mentioned below. - -* In general, we prefer that you do not remove or modify existing content unless it is clearly incorrect or out of date. - -* Pages with DRAFT at the top are in progress and will often contain unusual content, formatting, or notes. Please do not remove or modify these. That will all be corrected/removed upon final edit. - - -~-[[#ToC|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 [[#specifics|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 [[SGWikiBasics#color2|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 [[SGWikiBasics|Wiki Basics]] Style Guide or contact us at <>. - - - -~-[[#ToC|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_EnumerationName =``` - -For enumeration pages this is the name of the enumeration being described on the page and should match the address of the page. - -''Example'': The page address ```https://wiki.libsdl.org/SDL_EventType``` should have matching title {{{SDL_EventType}}} and describe the [[SDL_EventType]] structure. - -If you believe a change is necessary please submit ''Feedback'' from that page or contact us at <>. - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Description === -The Description section immediately follows the page title and does not have it's own heading. - -'''Enumeration descriptions begin with: - ```An enumeration of```''' - or very rarely - ```A hint that specifies``` - -: followed by a ''clear and concise'' description of what the enumeration (or hint) is. - - -''Note'': Information presented in this section is meant to be limited. Extended description information for more complicated enumerations should be placed in the [[#Remarks|Remarks]] section instead. -* The Description should not contain a link to the Remarks section even if additional information is located there. - -''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 hint__ rather than an enumeration -|''Action'': Use the alternate description (A hint that specifies...) and, if necessary, replace the word enumeration with the word hint where appropriate throughout the page. -|- -|''Example'': [[SDL_EventType]], [[SDL_HINT_RENDER_SCALE_QUALITY]] -|- -|<( |2 30%>''If'' __another API page__ is referenced in the description -|''Action'': Be sure to [[SGWikiBasics#Hyperlinks|hyperlink]] it and use () outside the link markup if it is a function. -|- -|''Example'': ```[[SDL_FunctionName]](), [[SDL_StructureName]]```, [[SDL_BlendMode]] -|- -|<( 30%>''If'' __a value on that page__ is referenced in the description -|''Action'': There is no special formatting for enumeration values since most are already in all caps and distinct enough. (This is different from function parameters or structure data values.) -|} - - -~-[[#ToC|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. - ```<>``` - -If you believe a change is necessary please submit ''Feedback'' from that page or contact us at <>. - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Values === -The Values section provides basic information about each value in the enumeration and is presented in table format. - -'''The basic format is as follows:''' -``` -||value1||description|| -||value2||description|| -... -||valueN||description|| -``` - -''Markup'': Use [[SGWikiBasics#Tables|basic table markup]]. All text in the table is left-justified. Do not use bold. - -* The __first column__ contains the value name, usually in all caps (format as in the API). -* The __second column__ contains a simple description of each value using some specific formatting conventions. -: ''Important!'' All descriptions begin with a ''lower case'' letter, end ''without'' a period, and are generally ''not'' complete sentences. - -''Example'': [[SDL_BlendMode]], [[SDL_HintPriority]], [[SDL_PowerState]], [[SDL_WindowFlags]] - -''Action'': There are a few content-dependent conventions we have chosen for consistency across pages. See the tables below for details. - -{| -| -|''General (whole table)'' -|- -|<( |5 30%>''If'' the value 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:
`````` -|- -|''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. -|- -|''Markup'': ``` -|value -|description -|``` -|- -|''Example'': [[SDL_EventType]], [[SDL_LOG_CATEGORY]] -|- -|<( |3 30%>''If'' the value is specified as __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'' values are read-only notate it in the Remarks instead. -|- -|''Note'': This also applies to the rare case that "(read-write)" is specified. -|- -|''Example'': There are currently no enumeration examples of this. [[SDL_Surface]], [[SDL_PixelFormat]] -|- -|<( |3 30%>''If'' __another API page__ is referenced ''and'' __the value is greyed out__ (see [[#grey|above]]) -|''Action 1'': DO NOT hyperlink the page in the table. -|- -|''Action 2'': List the page, with a hyperlink, in the description and/or in the appropriate "Related" section at the bottom of the page, if appropriate. -|- -|''Example'': There are currently no enumeration examples of this. [[SDL_Event]] -|- -|<( |3 30%>''If'' __another API page__ is referenced ''and'' __the value is ''not'' greyed out__ (see [[#grey|above]]) -|''Action1'': Be sure to [[SGWikiBasics#Hyperlinks|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'': There are currently no enumeration examples of this. [[SDL_Event]], [[SDL_BlendMode]] -|- -|<( |4 30%>''If'' there are __important, distinct groups of values__ within the enumeration -|''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: 1 empty cell for a 2 column table). Place the following markup in the last cell
''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_AudioFormat]], [[SDL_EventType]] -|- -| -|''Specific (description column)'' -|- -|<( |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 __[[#detailed|more detailed description]]__ is required to adequately explain a value" below for more details. -|- -|''Example'': [[SDL_HintPriority]], [[SDL_GLattr]] -|- -|<( |4 30%>''If'' a __more detailed description__ is required to adequately explain a value -|''Action 1'' : Append the following, verbatim, to the end of the brief description
```; see [[#Remarks|Remarks]] for details``` -|- -|''Action 2'': Place the more detailed information in the [[#Remarks|Remarks]] section. -|- -|''Action 3'': See "''If'' the __[[#large|Remarks section is large]]__" below for more details. -|- -|''Example'': [[SDL_PixelFormatEnum]], [[SDL_GLattr]] -|- -|<( |4 30%>''If'' the __Remarks section is large__ -|''Action 1'': Create an [[SGWikiBasics#Anchors|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 [[SGWikiBasics#Anchors|Anchors]] for details. -|- -|''Action 2'': Modify the Remarks link in the parameter description (see ''Action 1'' in "''If'' a __[[#detailed|more detailed description]]__ is required to adequately explain a value" above) to the following:
```; see [[#anchorname|Remarks]] for details```
where anchorname matches the name you chose for the anchor in ''Action 1''. -|- -|''Example'': [[SDL_GLattr]], [[SDL_PixelFormatEnum]] -|- -|<( |3 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. -|- -|''Note'': If ''none'' of the values has relevant description text it is acceptable to remove the entire description column, but this should be done with caution and only extremely rarely. -|- -|''Example'': [[SDL_PixelFormatEnum]], [[SDL_AudioStatus]], [[SDL_HINT_RENDER_DRIVER]] -|} - - - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Code Examples === -The Code Examples section is meant to contain simple, meaningful examples of how to use the enumeration in a program. -* Unlike other sections, which should rarely require editing once DRAFT is removed, this section is ''expected'' to change over time. - -This is one of the few sections that is intended to grow and adjust as users discover more information about an enumeration 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 [[SGCodeExamples|Code Examples]] Style Guide for details on editing this section.''' - - -~-[[#ToC|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 enumeration in real-world applications. -* Unlike other sections, which should rarely require editing once DRAFT is removed, this section is ''expected'' to change over time. - -This is one of the few sections that is intended to grow and adjust as users discover more information about how an enumeration 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 [http://forums.libsdl.org/ forums] and [http://www.libsdl.org/mailing-list.php mailing lists], for these types of remarks. - -'''Please see the [[SGRemarks|Remarks]] Style Guide for details on editing this section.''' - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Related Enumerations === -The Related Enumerations section provides a list of enumerations specifically referenced by the enumeration or otherwise ''closely'' related to it. '''This section is very rarely used.''' - -'''This list __should__ include:''' -* other enumerations that are specifically referenced in the enumeration (may never occur) -* other enumerations that are indirectly referenced by or ''very'' closely related to the enumeration -: ~-(ie: the enum is not used as a value but its values are used to fill in a value or they are different aspects of the same idea)-~ -: ~-This is very uncommon.-~ - -'''This list __should not__ include:''' -* the primary enumeration on that page -* every enumeration that might be considered "related" to the enumeration or any other listed enumerations -: ~-Including too many would make these lists much less valuable.-~ -* all enumerations of similar type -* all enumerations of a related category -* enumerations that are indirectly related -: ~-(ie: it might be common to use them together)-~ -* enumerations that do not have a page in the wiki -* non-enumerations -: ~-(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 [[SGWikiBasics#Hyperlinks|hyperlink]]. -: ''Note'': Do not include empty parentheses after the name. - -: '''The basic format for the Related Enumerations list is:''' -``` -== Related Enumerations == - .[[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. -|- -|<( |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_Keycode]], [[SDL_Scancode]] - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Related Structures === -The Related Structures section provides a list of structures (or unions) specifically referenced by the enumeration or otherwise ''closely'' related to it. - - -'''This list __should__ include:''' -* structures that specifically reference the enumeration -* structures that indirectly reference but are closely related to the enumeration -: ~-This is uncommon.-~ - -'''This list __should not__ include:''' -* every other structure that might be considered "related" -: ~-Including too many would make these lists much less valuable.-~ -* all structures of similar type -* all structures of a related category -* structures that are indirectly related -: ~-(ie: it might be common to use them together)-~ -* structures that do not have a page in the wiki -* non-structures -: ~-(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 [[SGWikiBasics#Hyperlinks|hyperlink]]. -: ''Note'': Do not include empty parentheses after the name. - -: '''The basic format for the Related Structures list is:''' -``` -== Related Structures == - .[[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_AudioFormat]], [[SDL_BlendMode]], [[SDL_PixelFormatEnum]] - - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- -=== Related Functions === -The Related Functions section provides a list of functions specifically associated with that enumeration or otherwise ''closely'' related to it. -* In general, a "Related Function" is one that __uses the given enumeration__. - -'''This list __should__ include:''' -* functions that use or are otherwise very closely related to the enumeration - -'''This list __should not__ include:''' -* every other function that might be considered "related" -: ~-Including too many would make these lists much less valuable.-~ -* all functions of similar type or action -* all functions of a related category -* functions that are indirectly related (ie: a similar function that does not use the structure) -* functions that do not have a page in the wiki -* non-functions (ie: do not include structures or enumerations in this list) - -''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 [[SGWikiBasics#Hyperlinks|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:''' -``` -== Related Functions == - .[[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_AudioStatus]], [[SDL_HintPriority]], [[SDL_TextureAccess]] - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- -=== Footer === -{| -|''Important!''
See [[#hints|Hint Pages]] below for details on how this section is different for Hint pages. -|} - -The Footer section consists of a horizontal rule followed by two links separated by a comma. - -''Markup'': -``` ----- -[[CategoryEnum]], [[CategoryHeader]] -``` -: where CategoryEnum is the same for every enumeration page and CategoryHeader is enumeration-specific with Header varying based on the header file containing the enumeration (see below). - -''Important!'' Category names do not always match the header file name. Please consult the following [[#CategoryTable|table]] for the correct name to use so the enumeration will appear in the correct list(s). - -''Action 1'': '''Do not edit the CategoryEnum link!''' - -''Action 2'': '''The ```CategoryHeader``` link may be edited''' ''if'' the page still says {{{[[CategoryHeader]]}}} (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 according to the table). 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 your concern in the [http://forums.libsdl.org/ forums] or [http://www.libsdl.org/mailing-list.php mailing lists] or contact us at <> to confirm the change first. - -''Markup'': Replace CategoryHeader with the appropriate category name from the table that follows, or contact us at <> to find out what category name to use if you are unsure or if the category appears to be missing. - - -{| -|''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.-~ -|} - - - - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- -=== Special === -This section contains details for special formatting circumstances that are best described separately from the average enumeration page. In general these guidelines should be used in conjunction with the above. - - -==== Hint Pages ==== -In some cases Hints are formatted slightly differently than enumerations. '''Use the following formatting specifics in addition to those listed above for all [[CategoryHints|CategoryHints]] pages:''': - -''Action 1'': All Hint pages contain an additional section not present on enumeration pages - Default - -''Markup'': Add the following section to all CategoryHints pages between the Values and Code Examples sections. - ``` -== Default == -``` -: ''Action'': Immediately under this section include at least one sentence beginning with the following, and describing the default state, if any, for that hint: - By default... - -''Example'': [[SDL_HINT_FRAMEBUFFER_ACCELERATION]], [[SDL_HINT_RENDER_SCALE_QUALITY]] - - -''Action 2'': The [[#Footer|Footer]] section of a Hint page follows the same guidelines as for an enumeration page with the following differences: -: Use ```[[CategoryDefine]], [[CategoryHints]]``` as the link pair at the bottom instead. -: The table above is irrelevant to this section since they are all the same. - -''Note'': To date there are no Related Enumerations, Related Structures, or Related Functions listed on any Hint page. Should there be, follow the same general guidelines as for enumerations. - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- - - -<> diff --git a/SDL2/SGFunctions.mediawiki b/SDL2/SGFunctions.mediawiki deleted file mode 100644 index e42792052..000000000 --- a/SDL2/SGFunctions.mediawiki +++ /dev/null @@ -1,942 +0,0 @@ - - -= Style Guide: Function Pages = -This guide provides specific instructions for editing or adding your own content to each section of a Function page in this wiki. - -'''Function pages should provide basic information about the SDL functions to allow users to most effectively utilize them in their projects.''' - - - - -== General Guidelines == -{| -|Important note about '''Macros'''
The basic function template is also used for macros that have pages in the wiki. For simplicity, the following guidelines for functions will also apply to macros unless a specific difference is noted. -|} - -'''Please observe the following for all function pages:''' -* Do not post anything that you do not have permission to post publicly. - -* Sections should have adequate details to make them clear and useful while remaining brief wherever possible. Code Examples and Remarks may be more extensive than other sections if necessary. - -* Please remember to keep it accurate, simple, and easy to understand. - -* Do not remove, modify, or add to the markup above the page title (#pragma or #acl processing instructions, etc.) except: -* On CategoryCompat pages, place the following markup above the page title, below the processing instructions or DRAFT markup if present: -: ```||
~+For Backward Compatibility Only+~

||``` - -* Do not remove, modify, or add section headings unless specifically mentioned below. - -* In general, we prefer that you do not remove or modify existing content unless it is clearly incorrect or out of date. - -* Pages with DRAFT at the top are in progress and will often contain unusual content, formatting, or notes. Please do not remove or modify these. That will all be corrected/removed upon final edit. - - - -~-[[#ToC|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 [[#specifics|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 [[SGWikiBasics#color2|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 [[SGWikiBasics|Wiki Basics]] Style Guide or contact us at <>. - - - -~-[[#ToC|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_FunctionName =``` - -For function pages this is the name of the function being described on the page and should match the address of the page. - -''Example'': Page address ```https://wiki.libsdl.org/SDL_CreateWindow``` should have matching title {{{= SDL_CreateWindow =}}} and describe the [[SDL_CreateWindow]]() function. - -If you believe a change is necessary please submit ''Feedback'' from that page or contact us at <>. - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Description === -The Description section immediately follows the page title and does not have it's own heading. - -'''All function descriptions begin with: - ```Use this function to```''' - or very rarely - ```Use this macro to``` - -: followed by a ''clear and concise'' description of what the function does. - - -''Note'': Information presented in this section is meant to be limited. Extended description information for more complicated functions should be placed in the [[#Remarks|Remarks]] section instead. -* The Description should not contain a link to the Remarks section even if additional information is located there. - -{| -|<( |3 30%>''If'' the page describes __a macro__ rather than a function -|''Action'': Use the alternate description (Use this macro to...) and, if necessary, replace the word function with the word macro where appropriate throughout the page. -|- -|''Note'': In some rare cases it has been deemed appropriate to refer to a macro as a function in the wiki. (eg: [[SDL_QuitRequested]]()) This is not accidental. Please do not "correct" these instances. If you feel strongly that a change should be made please contact us. -|- -|''Example'': [[SDL_VERSION]]() -|- -|<( |2 30%>''If'' __another API page__ is referenced in the description -|''Action'': Be sure to [[SGWikiBasics#Hyperlinks|hyperlink]] it and use () outside the link markup if it is a function. -|- -|''Example'': ```[[SDL_FunctionName]](), [[SDL_StructureName]]```, [[SDL_GetThreadName]]() -|- -|<( |3 30%>''If'' __a parameter__ on that page is referenced in the description -|''Action'': Use '''[[SGWikiBasics#Text_Formatting|bold]]''' for the parameter name. -|- -|''Note'': This is a very rare occurrence. -|- -|''Note'': If the reference is to the parameter as a ''concept'' (ie: the window to do something with) rather than ''directly'' to the parameter itself (ie: SDL_Function(window)) do not make it bold.
~-Please don't just make the word bold every time it occurs on the page.-~ -|} - - - - -~-[[#ToC|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. - ```<>``` - -If you believe a change is necessary please submit ''Feedback'' from that page or contact us at <>. - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Syntax === -The Syntax section consists of a code box that displays the basic components of the function using some specific formatting conventions. Please apply the following conventions when editing this section. - -'''The basic format is as follows:''' -```{ -{{{#!highlight cpp -returnType* SDL_FunctionName(type1 parameter1, - type2* parameter2, - ... - typeN parameterN) -``` -}}}} - -''Important!'' All types and parameters should be vertically aligned. -* Spacing for parameter __types__ is left-aligned to the type on the first line. -* Spacing for __parameters__ is left-aligned to the longest param type so that there is only 1 space between the longest type (with any pointers) and its parameter. -* __Pointers__ (*, **) should be aligned next to the types (no space between) and should have at least one space following. - -''Markup'': Use spaces as necessary to create the correct alignment. Within a code box spacing is fixed-width. - -''Note'': __To be omitted__ -* All additional text that may be found in the header or elsewhere, such as extern, SDLCALL, etc. -* The space between SDL_FunctionName and (. -* Ending semi-colon (;) - -''Note'': __To be included__ -* The code box and colorizing markup above and below the function syntax
``````c++```
}}} - * A single space between `returnType` and `SDL_FunctionName` - * Commas at the end of each line before the last if there is more than 1 parameter - * The parentheses enclosing the parameters - -''Note'': Do not remove or alter the code box markup surrounding the function syntax. The starting and ending markup must remain on separate lines above and below the rest of the content in order to generate the code box. - -||<( |3 30%>''If'' a function refers to a __callback function__||''Action'': See the special section on callback functions [[#callback|below]].|| -||''Note'': Callback functions do not get their own pages.|| -||''Example'': [[SDL_AddEventWatch]](), [[SDL_AddTimer]]()|| - -''Example'': {{{{ -{{{#!highlight cpp - - 1 space no space spaces (as needed) - | \ |_________| -SDL_AudioSpec* SDL_LoadWAV_RW(SDL_RWops* src, - int freesrc, - SDL_AudioSpec* spec, <- longest type - Uint8** audio_buf, sets alignment - Uint32* audio_len) -|||||||||||||||||||||||||||||| \ | - spaces (as needed) no space 1 space -``` -}}}} - - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- -=== Function Parameters === -The Function Parameters section provides basic information about each parameter in the function and is presented in table format. - -''Important!'' -{| -|<( |2 30%>''If'' the only parameter is '''__void__''' -|''Action'': Delete the entire Function Parameters section, including the header. -|- -|''Example'': [[SDL_AllocRW]]() -|} - -Otherwise, '''function parameters follow this basic format:''' - -``` -||'''parameter1'''||description|| -||'''parameter2'''||description|| -... -||'''parameterN'''||description|| -``` - -''Markup'': Use [[SGWikiBasics#Tables|basic table markup]] and enclose each parameter name in [[SGWikiBasics#Text_Formatting|bold]] markup. All text in the table is left-justified. - -* The __first column__ contains the parameter names, without types or pointers, in bold. -* The __second column__ contains a simple description of each parameter using some specific formatting conventions. -: ''Important!'' All descriptions begin with a ''lower case'' letter, end ''without'' a period, and are generally ''not'' complete sentences. - -* There are a few content-dependent conventions we have chosen for consistency across pages - see the tables below for details. - -''Example'': [[SDL_SetColorKey]]() - -{| -| -|''Content-dependent formatting: General'' -|- -|<( |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 __[[#detailed|more detailed description]]__ is required to adequately explain a parameter" below for more details. -|- -|''Example'': [[SDL_PixelFormatEnumToMasks]]() -|- -|<( |4 30%>''If'' a __more detailed description__ is required to adequately explain a parameter -|''Action 1'' : Append the following, verbatim, to the end of the brief description
```; see [[#Remarks|Remarks]] for details```. -|- -|''Action 2'': Place the more detailed information in the [[#Remarks|Remarks]] section. -|- -|''Action 3'': See "''If'' the __[[#large|Remarks section is large]]__" below for more details. -|- -|''Example'': [[SDL_CreateWindow]]() -|- -|<( |3 30%>''If'' the __Remarks section is large__ -|''Action 1'': Create an [[SGWikiBasics#Anchors|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 [[SGWikiBasics#Anchors|Anchors]] for details. -|- -|''Action 2'': Modify the Remarks link in the parameter description (see ''Action 1'' in "''If'' a __[[#detailed|more detailed description]]__ is required to adequately explain a parameter" above) to the following:
```; see [[#anchorname|Remarks]] for details```
where anchorname matches the name you chose for the anchor in ''Action 1''. -|- -|<( |2 30%>''If'' __there is a pointer__ associated with the parameter -|''Action'': Avoid mentioning pointers unless they are critical to understanding the parameter or there is little other way to describe it (ie: void*) -|- -|''Example'': [[SDL_SetColorKey]]() -|- -|<( |2 30%>''If'' a pointer points to __something that is filled in by the function__ or that __has been filled in__ -|''Action'': Use the phrase filled in with in the description -|- -|''Example'': [[SDL_QueryTexturePixels]]() -|- -|<( |4 30%>''If'' the description mentions __a structure that has a page__ -|''Action 1'': Use the following pattern to describe the parameter:
the/an ```[[SDL_StructureName]]``` structure to or representing -|- -|''Action 2'': Check the [[#specific|table below]] for structure-specific phrasing. -|- -|''Note'': Be sure to hyperlink the structure name as shown in ''Action 1'' in the type and description columns (as appropriate) '''''except''''' if the row is greyed out (see ''If'' the parameter is __[[#grey|for internal use, deprecated, or private]]__ for details). -|- -|''Example'': [[SDL_UnionRect]]() -|- -|<( |3 30%>''If'' the description mentions __a structure that ''does not'' have a page__ -|''Action'': Use the plain English term to describe the structure (ie: SDL_Window == the window) and omit the hyperlink. -|- -|''Note'': Please check the current wiki before selecting this option for wording, as a page may have been created since this was written or since you last checked. -|- -|''Example'': [[SDL_RenderClear]]() -|- -|<( |2 30%>''If'' the description mentions __an enumeration__ -|''Action'': It is not necessary to specifically describe it as an enumeration as above for structures, but DO hyperlink if it has a page '''''except''''' if the row is greyed out (see ''If'' the parameter is __[[#grey|for internal use, deprecated, or private]]__ for details). -|- -|''Example'': [[SDL_PixelFormat]] -|- -|<( |1 30%>''If'' a description must refer to any other __page in the API__ -|''Action'': Create a [[SGWikiBasics#Hyperlinks|hyperlink]] to the page '''''except''''' if the row is greyed out (see ''If'' the parameter is __[[#grey|for internal use, deprecated, or private]]__ for details). -|- -|<( |5 30%>''If'' the parameter is __for internal use, deprecated, or private__ -|''Action 1'': 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:
`````` -|- -|''Action 2'': Include the reason (ie: internal use, etc.) in parentheses at the end of the description. -|- -|''Action 3'': DO NOT hyperlink any related API pages (ie: structure type) on greyed out parameters. -|- -|''Example'': ``` -|'''param''' -|description (reason) -|```, [[SDL_PixelFormat]] -|- -|''Note'': Although a rare case, any other table style markup should be included within the same set of angle brackets (<>) and separated from this markup by a space. -|- -|<( |3 30%>''If'' a function refers to a __callback function__ -|''Action'': See the special section on callback functions [[#callback|below]]. -|- -|''Note'': Callback functions do not get their own pages. -|- -|''Example'': [[SDL_AddEventWatch]](), [[SDL_AddTimer]]() -|- -|<( |4 30%>''If'' __a parameter references another parameter__ on that same page -|''Action'': Use '''[[SGWikiBasics#Text_Formatting|bold]]''' for the parameter name. -|- -|''Note'': This is a very rare occurrence. -|- -|''Note'': If the reference is to the parameter as a ''concept'' (ie: the window to do something with) rather than ''directly'' to the parameter itself (ie: SDL_Function(window)) do not make it bold.
~-Please don't just make the word bold every time it occurs on the page.-~ -|- -|''Example'': [[SDL_EnclosePoints]]() -|- -|<( |3 30%>''If'' a description is referring to something that could be __any one of a group of similar items__ (ie: rectangles) -|''Action'': Begin the description with a/an -|- -|''Example'': [[SDL_HasIntersection]]() -|- -|''Note'': We realize that this is a somewhat arbitrary distinction depending upon your perspective. If you are unsure whether to use a/an or the it may be helpful to do a quick text search for other pages with the same or similar parameter and copy the format there. Ultimately, though, it's not worth losing sleep over. ;) Just pick one. -|- -|<( |3 30%>''If'' a description is referring __to a specific item from a group__ (ie: a specific window) -|''Action'': Begin the description with the -|- -|''Example'': [[SDL_BlitScaled]]() -|- -|''Note'': We realize that this is a somewhat arbitrary distinction depending upon your perspective. If you are unsure whether to use a/an or the it may be helpful to do a quick text search for other pages with the same or similar parameter and copy the format there. Ultimately, though, it's not worth losing sleep over. ;) Just pick one. -|} - - -''Note'': It would only rarely be appropriate to use the exact same description of a common parameter every time that parameter appears in the API. However, the same or very similar description can be used for many occurrences of the same parameter, enhancing consistency across pages. The following table provides a list of these commonly used descriptions. - -''Action'': When choosing a description phrase for a parameter please check this list to see if any of these common descriptions is applicable, even if a minor modification is required. - - -{| -| -|''Content-dependent formatting: Specific'' -|- -|<( |4 30%>''If'' the parameter is __SDL_Palette* palette__ -|''Action 1'': Most often this description begins with the [[SDL_Palette]] structure to, followed by what to do with the palette (ie: free, modify, etc.). -|- -|''Action 2'': The most common version is the [[SDL_Palette]] structure to use -|- -|''Example'': [[SDL_SetSurfacePalette]](), [[SDL_FreePalette]]() -|- -|''Note'': Of course other phrases to describe this parameter may become necessary. A text search for "SDL_Palette* palette" should provide you with other descriptions if they arise. -|- -|<( |4 30%>''If'' the parameter is __SDL_Rect* rect(s)__ -|''Action 1 - __rect__'': Most often this description begins with the/an ```[[SDL_Rect]]``` structure representing the rectangle to, followed by what the rectangle is for (ie: fill, draw, intersect, etc). -|- -|''Action 2 - __rects__'': When the parameter is plural it refers to an array of rectangles and will most often begin with an array of ```[[SDL_Rect]]``` structures representing the rectangles to, followed by what the rectangles are for. -|- -|''Example'': [[SDL_FillRect]](), [[SDL_RenderDrawRect]](), [[SDL_IntersectRectAndLine]](), [[SDL_RenderDrawRects]]() -|- -|''Note'': Of course there are some other phrases to describe these parameters. A text search for "SDL_Rect* rect" should provide you with plenty of other examples of both the singular and plural parameters. -|- -|<( |3 30%>''If'' the parameter is __SDL_Renderer* renderer__ -|''Action'': A rare exception (at least so far), this description is __always__ the rendering context. -|- -|''Important!'' Please use the rendering context for ''all'' occurrences of this parameter unless/until it appears in the API in a different context that calls for another description. A text search for "SDL_Renderer* renderer" should be used to determine if this has become the case. -|- -|''Example'': [[SDL_RenderPresent]](), [[SDL_RenderDrawLine]](), [[SDL_CreateTexture]]() -|- -|<( |5 30%>''If'' the parameter is __SDL_Surface* surface__ -|''Action 1'': Most often this description begins with the [[SDL_Surface]] structure to, followed by what is happening with the structure (ie: optimize, be locked, etc.). -|- -|''Action 2'': The most common versions are the [[SDL_Surface]] structure to update (often used with Set functions) or the [[SDL_Surface]] structure to query (often used with Get functions). -|- -|''Action 3'': Some will be best described by the following instead: the [[SDL_Surface]] structure representing . -|- -|''Example'': [[SDL_SetSurfaceRLE]](), [[SDL_LockSurface]](), [[SDL_GetClipRect]](), [[SDL_SaveBMP_RW]]() -|- -|''Note'': Of course there are some other phrases to describe this parameter. A text search for "SDL_Surface* surface" should provide you with plenty of other examples. -|- -|<( |4 30%>''If'' the parameter is __SDL_Texture* texture__ -|''Action 1'': Most often this description begins with the texture to, followed by what is being done (ie: create, destroy, etc.). -|- -|''Action 2'': The most common versions are the texture to update (often used with Set functions) or the texture to query (often used with Get functions). -|- -|''Example'': [[SDL_SetTextureAlphaMod]](), [[SDL_QueryTexturePixels]](), [[SDL_UnlockTexture]]() -|- -|''Note'': Of course there are some other phrases to describe this parameter. A text search for "SDL_Texture* texture" should provide you with plenty of other examples. -|- -|<( |4 30%>''If'' the parameter is __SDL_Window* window__ -|''Action 1'': Most often this description begins with the window to, followed by what is being done (ie: minimize, maximize, show, etc). -|- -|''Action 2'': The most common versions are the window to change (often used with Set functions) or the window to query (often used with Get functions). -|- -|''Example'': [[SDL_RestoreWindow]](), [[SDL_SetWindowTitle]](), [[SDL_GetWindowFlags]]() -|- -|''Note'': Of course there are some other phrases to describe this parameter. A text search for "SDL_Window* window" should provide you with plenty of examples. -|- -|<( |3 30%>''If'' the parameters include __fmt and '''...'''__ -|''Action'': For fmt use a printf() style message format string
For '''...''' use additional parameters matching % tokens in the '''fmt''' string, if any. -|- -|''Note'': To date this is the only context for the '''...''' parameter. If your case does not follow this pattern exactly it may be necessary to make some adjustments. Please keep them as minimal as possible while creating an accurate wiki entry. -|- -|''Example'': [[SDL_SetError]](), [[SDL_Log]]() -|} - - - - - - - - -''Note'': Please do not use Includes in this section. It may occasionally be appropriate to copy and paste the parameters and descriptions from one function to another (perhaps with minor changes). This is the preferred method over using an Include. - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Return Value === -The Return Value section provides basic information about what, if anything, a function will return upon success or failure. - -''Important!'' -{| -|<( |3 30%>''If'' the return value is '''__void__''' -|''Note'': This is '''not''' the same as __void*__! See the table below for [[#void*|void*]] return values. -|- -|''Action'': Delete the entire Return Value section, including the header. -|- -|''Example'': [[SDL_FreeSurface]]() -|} - - -Otherwise, '''return values follow this basic format:''' - ``` -Returns on success or on failure; call [[SDL_GetError]]() for more information. -``` - -Use the following tables to determine what to replace and with in the standard statement above, and to determine whether some other action is required. - - - - - -* Please check both tables. - -{| -| -|''Replacements by type'' -|- -|<( 30%>''If'' the return value is __an int (0 or <0)__ -|''Action'': Use Returns 0 on success or a negative error code on failure; call [[SDL_GetError]]() for more information. -|- -|<( |2 30%>''If'' the return value is __an int other than above or a float__ -|''Action'': Replace and with the applicable numbers. -|- -|''Example'': Returns 1 on success or 0 on failure; call [[SDL_GetError]]() for more information. -|- -|<( 30%>''If'' the return value is __SDL_bool__ -|''Action'': Use Returns SDL_TRUE on success or SDL_FALSE on failure; call [[SDL_GetError]]() for more information. -|- -|<( |3 30%>''If'' the return value is __a pointer or NULL__ -|''Action'':Replace with an appropriate description of the pointer (usually leaving out any mention of the pointer, as in parameters) and replace with NULL. -|- -|''Note'': See "''If'' the return value type is __a structure__" below for more details. -|- -|''Example'': [[SDL_HapticOpen]](), [[SDL_GetRenderer]]() -|- -|<( |3 30%>''If'' the return value type is __a structure__ -|''Action'': The general format will approximate: Returns an/the ```[[SDL_StructureName]]``` representing , for success. The failure statement will depend upon what is returned on failure, if anything. See other ''If''s for options. -|- -|''Note'': Ideally in this case, you would search for other functions using the same return value and replicate the phrasing of others as appropriate. (Example search: "returnValue SDL_", where returnValue is replaced with the value you are interested in.) -|- -|''Example'': [[SDL_CreateRGBSurfaceFrom]]() -|- -|<( |3 30%>''If'' the return value is __void*__ -|''Action'':See "''If'' the return value is __[[#null*|a pointer or NULL]]__" above. -|- -|''Note'': In most cases it ''will'' be appropriate to mention the pointer for void*. Ideally, look at other similar functions for guidance. -|- -|''Example'': [[SDL_LoadFunction]](), [[SDL_SetWindowData]]() -|- -|<( |3 30%>''If'' the return value type is __a Uint__ -|''Action'': Replace with a brief, appropriate description of the Uint. -|- -|''Example'': [[SDL_MapRGBA]](), [[SDL_WasInit]]() -|- -|''Note'': Very rarely the Uint that is returned is a mask of enumerated values. See [[SDL_MasksToPixelFormatEnum]]() for an example of how to handle this. -|- -|<( |2 30%>''If'' the return value type is __a char or const char__ -|''Action'': Replace with a brief, appropriate description of the returned string. -|- -|''Example'': [[SDL_GetCurrentVideoDriver]]() -|- -|<( |2 30%>''If'' there are __more than 2__ possible return values -|''Action'': Add any additional values following the applicable rules above. Keep the primary success and primary failure values first and last, respectively, or place them in some other logical order (such as numerical). -|- -|''Example'': [[SDL_HapticOpened]](), [[SDL_OpenAudio]]() -|- -|<( |4 30%>''If'' the function __does not have a failure state__ -|''Note'': It is ''very rare'' for a function to be unable to fail. This option covers those rare cases only. -|- -|''Action 1'': ''If'' the function only has 1 return value state:
Omit the second part of the statement and omit the call to SDL_GetError(). -|- -|''Action 2'': ''If'' the function has 2 return values but they don't represent success and failure:
Use Returns or otherwise.
and omit the call to SDL_GetError(). -|- -|''Example'': only 1 return state [[SDL_GetAudioDeviceStatus]](); alternate return state [[SDL_QuitRequested]]() -|} - - -{| -| -|''Replacements by other criteria'' -|- -|<( |4 30%>''If'' __a parameter__ on that page is referenced in the return value -|''Action'': Use '''[[SGWikiBasics#Text_Formatting|bold]]''' for the parameter name. -|- -|''Note'': This is a very rare occurrence. -|- -|''Note'': If the reference is to the parameter as a ''concept'' (ie: the window) rather than ''directly'' to the parameter itself (ie: window) 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_GL_CreateContext]]() -|- -|<( |3 30%>''If'' the return value mentions __a structure that has a page__ -|''Action'': Use the following pattern to describe the return value:
Returns the/an ```[[SDL_StructureName]]``` structure representing of information> -|- -|''Note'': Be sure to hyperlink the structure name as shown. -|- -|''Example'': [[SDL_UnionRect]]() -|- -|<( |2 30%>''If'' the return value mentions __a structure that ''does not'' have a page__ -|''Action'': Use the plain English term to describe the structure (ie: SDL_Window == window). -|- -|''Note'': These structures may eventually have pages or other references worth linking to, in which case please follow the instructions above for linking to items with pages of their own. -|- -|<( |2 30%>''If'' the return value must refer to any other __page in the API__ -|''Action'': Create a [[SGWikiBasics#Hyperlinks|hyperlink]] to the page. -|- -|''If'' the page is for an __enumeration__ it is not necessary to describe it as an enumeration as above for structures. -|} - -''Note'': It is extremely rare that an Include is appropriate in this section. If it were to occur it would only be to provide a list of possible return values that are based on an enumeration (or similar). In that case, please see the instructions for creating an Include in the [[SGWikiBasics#Includes|Wiki Basics]] style guide, and the Include section of the [[SGRemarks#Using_an_Include|Remarks]] style guide for details. -* ''If'' you use an Include in this section, please email <> telling us what page received the Include and what page was used as the source. We are keeping a list of all pages using Includes for future reference and this will help us to keep this list up to date. We appreciate your taking time for this extra step to help us keep our records accurate and useful. Thank you! - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Code Examples === -The Code Examples section is meant to contain simple, meaningful examples of how to use the function in a program. -* Unlike other sections, which should rarely require editing once DRAFT is removed, this section is ''expected'' to change over time. - -This is one of the few sections that is intended to grow and adjust as users discover more information about a function 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 [[SGCodeExamples|Code Examples]] Style Guide for details on editing this section.''' - - -~-[[#ToC|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 function in real-world applications. -* Unlike other sections, which should rarely require editing once DRAFT is removed, this section is ''expected'' to change over time. - -This is one of the few sections that is intended to grow and adjust as users discover more information about how a function 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 [http://forums.libsdl.org/ forums] and ''Feedback'' form, for these types of remarks. - -'''Please see the [[SGRemarks|Remarks]] Style Guide for details on editing this section.''' - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
-=== Related Functions === -The Related Functions section provides a list of other functions specifically referenced by that function or otherwise ''closely'' related to it. -* In general, a "Related Function" is one that is important to the __use__ or __understanding__ of the given function. - -'''This list __should__ include:''' -* the opposite function in a function pair (ie: get/set, do/undo) -* functions that represent close alternatives (ie: general and specific versions, singular and plural versions) -* functions that are called by or otherwise very closely related to the actions of the primary function on the page - -'''This list __should not__ include:''' -* the primary function on that page -* every other function that might be considered "related" -: ~-An argument can usually be made for a "relationship" between many functions. Including all of them would make these lists much less valuable.-~ -* all functions of similar type or action -* all functions of a related category -* functions that are indirectly related (ie: it might be common to use them together) -* functions that do not have a page in the wiki (usually because they are not public functions) -* non-functions (ie: do not include structures or enumerations in this list) - -''Note'': In most cases a Related Function reference should be reciprocal - if you include function B on the page for function A then function A should be included on the page for function B. - -''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 [[SGWikiBasics#Hyperlinks|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:''' -``` -== Related Functions == - .[[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. -|} - -''Note'': Function pages do not include a "Related Structures" or "Related Enumerations" section as some of the other page types do. If there are important related structures or enumerations they are to be included in the body of the page as links (usually in the Function Parameters or Remarks section). If you feel it is critical that a distinct section for one of these groups be included on a specific function page please submit ''Feedback'' from that page or contact us at <> to discuss it. - - - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- -=== Footer === - -The Footer section consists of a horizontal rule followed by two links separated by a comma. - -''Markup'': -``` ----- -[[CategoryAPI]], [[CategoryHeader]] -``` -: where CategoryAPI is the same for every function page and CategoryHeader is function-specific with Header varying based on the header file containing the function (see below). - -''Important!'' Category names do not always match the header file name. Please consult the following [[#CategoryTable|table]] for the correct name to use so the function will appear in the correct list(s). - -''Action 1'': '''Do not edit the CategoryAPI link!''' - -''Action 2'': '''The ```CategoryHeader``` link may be edited''' ''if'' the page still says {{{[[CategoryHeader]]}}} (as on a new page) or ''if'' the function 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 <> to confirm the change first. - -''Markup'': Replace CategoryHeader with the appropriate category name from the table that follows, or contact us at <> to find out what category name to use if you are unsure or if the category appears to be missing. - - -{| -|''Header File Containing the Function*'' -|''Corresponding Category Name'' -|- -|SDL.h -|CategoryInit -|- -|SDL_assert.h -|CategoryAssertions -|- -|SDL_atomic.h -|CategoryAtomic -|- -|SDL_audio.h -|CategoryAudio -|- -|SDL_clipboard.h -|CategoryClipboard -|- -|SDL_bits.h -|CategoryBits -|} - - -{| -|SDL_cpuinfo.h -|CategoryCPU -|- -|SDL_endian.h -|CategoryEndian -|- -|SDL_error.h -|CategoryError -|- -|SDL_events.h -|CategoryEvents -|- -|SDL_gamecontroller.h -|CategoryGameController -|} - -{| -|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.-~ -|} - - - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- - - -=== Special === -This section contains details for special formatting circumstances that are best described separately from the average function page. In general these guidelines should be used in conjunction with the above. - - -==== Callback Functions ==== -The presence of a callback function will affect two (2) sections of the main function's page - Function Parameters and Remarks. - -''Action 1'': '''Use the following formatting specifics in addition to those listed for the main function [[#Function Parameters|above]] whenever a callback function is included on a function page:''' - -{| -| -|''Function Parameters Section Formatting Details'' -|- -|<( |3 30%>For the parameter that refers to the __callback__ function -|''Action'': Use the following wording, modified as necessary, to describe the parameter:
the function to call /why>; see [[#Remarks|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 (such as '''filter''', '''fn''', or '''handler'''). -|- -|''Example'': [[SDL_LogSetOutputFunction]](), [[SDL_AddEventWatch]](), [[SDL_CreateThread]](), [[SDL_SetAssertionHandler]]() -|- -|<( |4 30%>For the parameter that passes __user data__ to the callback -|''Action'': Use the following wording, modified as necessary, to describe the parameter:
a pointer that is passed to '''callback'''
where callback is replaced with the callback function parameter name (if necessary). -|- -|''Note'': In rare cases, often 'Get' functions, this is a pointer to a pointer and should be described as such. -|- -|''Note'': This parameter is often named '''userdata''', but may have other names (such as '''data''' or '''param'''). It is important to distinguish this parameter from other parameters that are passed to the callback also, but that are not strictly carrying "user data" (such as '''interval''') and from other parameters that are unrelated to the callback function (such as '''name'''). See below for details. -|- -|''Example'': [[SDL_LogSetOutputFunction]](), [[SDL_CreateThread]](), [[SDL_AddTimer]](), [[SDL_LogGetOutputFunction]]() -|- -|<( |2 30%>For other parameters __related to the callback__ -|''Action'': There may be other parameters that are passed to the callback function but which are sufficiently different from the __[[#UserData|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 function parameters __''not'' related to the callback__ -|''Action'': Follow any applicable guidelines listed [[#Function Parameters|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: - {{{#!highlight cpp -callback syntax -``` -: where its parameters are: - ||callback parameter||description|| -: optional return value info... -: optional remarks or details... -}}}} -: 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... - -{| -| -|''Remarks Section Formatting Details'' -|- -|<( |2 30%>__Location__ -|''Action'': Generally the Remarks section is roughly organized in the same order as the function parameters. Callback details should be located accordingly, or at the top of the Remarks section if there isn't much else, but below any fundamental or critical remarks about the main function as a whole, if present. 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 [[#prototype|basic format]] above, only the first line should be left-justified. Everything else related directly to the callback should be [[SGWikiBasics#Indenting|indented]] one level (or more) to indicate it's relationship to the callback as opposed to the main function. -|- -|<( |2 30%>''If'' the callback parameter is __not '''callback'''__ -|''Action'': Replace '''callback''' in the [[#prototype|basic format]] above with the function parameter name used in the main function to refer to the callback function. -|- -|''Example'': [[SDL_SetEventFilter]](), [[SDL_CreateThread]](), [[SDL_SetAssertionHandler]]() -|- -|<( 30%>For __"callback syntax"__ in the [[#prototype|basic format]] above -|''Action'': Replace "callback syntax" with the callback function's syntax formatted the same as the main function's syntax. (See [[#Syntax|Syntax]] above for details.) -|- -|<( |2 30%>''If'' the __callback function name__ requires any explanation -|''Action'': Replace "where its parameters are:" in the [[#prototype|basic format]] above with the following:
where is explanation> and its parameters are:
replacing with the name of the callback function and explanation> with an explanation of the name (ie: your function name). -|- -|''Example'': [[SDL_AddEventWatch]]() -|- -|<( |4 30%>For __| callback parameter | description |__ in the [[#prototype|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 the main function '''''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):
```what was passed as '''userdata''' to [[SDL_MainFunctionName]]()```
replacing '''userdata''' with the appropriate parameter name if necessary, and replacing MainFunctionName with the name of the primary function 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 [[#prototype|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. -|- -|''Example'': [[SDL_AddEventWatch]](), [[SDL_AddTimer]]() -|- -|<( |2 30%>''If'' there are __"optional remarks or details"__ -|''Action'': Replace "optional remarks or details..." in the [[#prototype|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]]() -|} - - -
- -```{#!wiki comment -'''''This section has been left in for future reference if a compat section or similar is ever added back. It does not currently apply to any pages.''''' - -==== Compatibility Functions ==== -Compatibility functions are present in the API for backward compatibility only and thus are treated slightly differently than functions from the current version. '''Use the following formatting specifics in addition to those listed above for all [[#CategoryCompat|CategoryCompat]] pages:''': - -''Action 1'': The top of every compatibility function page should include the following, verbatim, to be placed below the pragma markup, below DRAFT if present, and above the page title: - {{{ -|| <
>~+For Backward Compatibility Only+~<
><
> || -``` - -''Action 2'': - ||<( |2 30%>''If'' __only one SDL 1.3 function__ replaces the compatibility function||''Action'': See ''Markup A'' below.|| - ||''Example'': [[]](), [[]]()|| - ||<( |3 30%>''If'' __more than one SDL 1.3 function__ has replaced the compatibility function||''Action'': See ''Markup B'' below.|| - ||''Note'': Listing more than two replacement functions should occur only rarely, if at all. Please avoid making this list any larger than necessary. This is NOT a related functions list!|| - ||''Example'': [[SDL_AudioDriverName]](), [[SDL_WM_ToggleFullScreen]]()|| - ||<( |2 30%>''If'' there are __no equivalent functions__ in SDL 1.3||''Action'': See ''Markup C'' below.|| - ||''Example'': [[SDL_Flip]](), [[]]()|| -
-: ''Markup A'': Add the following section to the end of the page above the footer. Replace SDL_Function with the name of the appropriate SDL 1.3 function: - ``` -== SDL 1.3 Replacement(s) a == -||'''This function has been replaced by the following in SDL 1.3: [[SDL_Function]]'''|| -``` -: ''Example'': [[]](), [[]]() -
-: ''Markup B'': Add the following section to the end of the page above the footer. Create a list of functions by repeating the [[SDL_Function]] markup, separating each member of the list with a comma, and placing the most direct counterpart first, alphabetizing any additional functions after that. - ``` -== SDL 1.3 Replacement(s) b == -||'''This function has been replaced by the following in SDL 1.3: [[SDL_Function]], [[SDL_Function]]'''|| -``` -: ''Example'': [[SDL_WM_ToggleFullscreen]](), [[SDL_WM_GrabInput]]() -
-: ''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) c == -||'''There are currently no equivalent functions in SDL 1.3.'''|| -Other options here -``` -: ''Example'': [[SDL_EnableKeyRepeat]]() (see other [[CategoryCompat]] pages for more examples) - -}}}} - - -~-[[#ToC|Return to Table of Contents]]-~ -
-
- - -<> diff --git a/SDL2/SGNewPages.mediawiki b/SDL2/SGNewPages.mediawiki deleted file mode 100644 index 99b48c66c..000000000 --- a/SDL2/SGNewPages.mediawiki +++ /dev/null @@ -1,97 +0,0 @@ - - -= Style Guide: New Pages = - -This guide provides instructions for adding new pages to this wiki. - -'''Most of the pages in the SDL API already exist and will only require editing as time goes on. See the other [[Contributing#guides|Style Guides]] for details on editing existing pages. But, if you encounter a component of the API that should have a page in this wiki but does not, this guide is your starting point.''' - - - - -== General Guidelines == -''This wiki contains the following page types:'' - ||[[CategoryAPI|API pages]]||pages describing the various Hints, Enumerations, Structures, and Functions of SDL|| - ||[[APIByCategory|Category pages]]||pages that list all parts of the API related to a specific topic, or category, and may contain some introductory discussion about the topic|| - ||[[Tutorials]]||pages that help people use SDL|| - ||Administrative pages||these include most of the other pages linked in the left sidebar, such as the [[FrontPage]], [[Introduction]], [[Support]], and [[Contributing]] pages|| - -''Important!'' '''It is highly unlikely that you will be creating new Administrative pages.''' If you feel that something of this nature is warranted, or if you feel an Administrative page needs editing, please contact us at <> or post about it in a [Contributing#list|Mailing List]] or [[http://forums.libsdl.org/ Forum]. - -''Action - Tutorials'': '''Please see the [[SGTutorials|Tutorials Style Guide]] if you wish to create a new Tutorial page.''' - -''Action - Other'': At present, all of the categories (headers) that will have a Category page (see a list [[SGFunctions#CategoryTable|here]]) and all of the Hints, Enumerations, Structures, and Functions that will have an API page in this wiki have been created. However, since SDL is a dynamic entity, should it become necessary to create a new Category or API page, please follow the instructions in the remainder of this Style Guide. - - -'''Please only create a new Category or API page if you are certain that it does not already exist and that it fits with and will enhance this documentation.''' -* Do not post anything that you do not have permission to post publicly. -* Please remember to keep it accurate, simple, and easy to understand. -* Please carefully follow the guidelines in this and the other [[Contributing#guides|Style Guides]] to ensure the continuing value and quality of this documentation. - -~-[[#ToC|Return to Table of Contents]]-~ -
- - -== Creating A New Page == -The basic steps required to create a new page in this wiki are the same regardless of page type. ''If'' you have determined that it is ''necessary'' to create a new page, begin here and use the following guidelines as they apply to your page type: - - -''Action 1'': '''Create an address for the page.''' - - ''How'': Type the following into the address bar and replace PageName with the name of your page. Press Enter to begin creating the page. - - ``` -https://wiki.libsdl.org/PageName -``` -: ~-Note: There are several ways to create a new page address. You may choose another method if you prefer.-~ - - ''Note'': The convention in this wiki is that the name of the page is also the address of the page and that CamelCase is preferable to blank spaces.
''Page addresses are case-sensitive.'' - - ''Example'': The address for the page [[SDL_BuildAudioCVT]]() is -: ```https://wiki.libsdl.org/SDL_BuildAudioCVT``` - - ''Important!'' '''Be careful to name and spell accurately when creating a new page! You cannot delete a page or edit a page address after the page is created and saved.''' - ||<( |2 30%>''If'' you discover a typo in the address __prior to saving the page__||''Action'': DO NOT SAVE THE PAGE! Copy any of your contents you'd like to save, Cancel or close the page, and start over.
Paste your contents into the new page and continue editing.|| - ||''Note'': Your old page and address will not be saved.|| - ||<( |2>''If'' you discover a typo in the address __after you saved the page__||''Action'': Send a message to <> requesting a correction.|| - ||''Note'': You will not be able to correct it yourself.|| - ''Note'': If you type in an address and land on an existing page then most likely you do __not__ need to create a page but may need to edit the existing one instead. If a new page is still required you will need to select a different address. - -''Action 2'': '''Choose the correct Template.''' - - ''How'': If you have chosen a unique address in ''Action 1'' [[#creating|above]] then you will arrive at a page that has the following at the top followed by a table with 2 columns. - ||'''This page does not exist yet. You can create a new empty page, or use one of the page templates.'''

Create new empty page|| -: Use the following table to determine which template to select. - - ||<( 30%>''If'' you need to create a new __Category page__||''Action'': See [[#category|Creating a Category Page]] below for further details|| - ||<( 30%>''If'' you need to create a new __API page__||''Action'': See [[#api|Creating an API page]] below for further details|| - - ''Note'': When editing a new page the default method is the Text editor. If you prefer to use the GUI editor click GUI/Text Mode in the left column to switch to the GUI editor on the new page. - - ''Note'': For information on markup used in this wiki see [[SGWikiBasics]]. - - -~-[[#ToC|Return to Table of Contents]]-~ -
- -=== Creating a Category Page === -''Action 1'': Select CategoryTemplate in the LEFT column of the table. - -''Action 2'': Follow the commented instructions (after ## at the beginning of a line) on the template page and use other Category pages as examples. There is no special Category Style Guide. Contact us if you need help or have questions. - -~-[[#ToC|Return to Table of Contents]]-~ -
- -=== Creating an API Page === -''Action 1'': In the LEFT column of the table click on: - ||SDLEnumTemplate||to create a page for an Enumeration or Hint|| - ||SDLFunctionTemplate||to create a page for a Function|| - ||SDLStructTemplate||to create a page for a Structure or Union|| - -''Action 2'': There are some very basic instructions commented (after ## at the beginning of a line) into the 3 templates, but these will be inadequate in most cases. Depending upon the type of API page, see the appropriate [[Contributing#guides|Style Guide]] for further details. - -~-[[#ToC|Return to Table of Contents]]-~ - - - -<> diff --git a/SDL2/SGRemarks.mediawiki b/SDL2/SGRemarks.mediawiki deleted file mode 100644 index 883df16b6..000000000 --- a/SDL2/SGRemarks.mediawiki +++ /dev/null @@ -1,181 +0,0 @@ - - -= Style Guide: Remarks = - -All [[SGWikiBasics#api|API pages]] in this wiki contain a section for remarks. This guide provides instructions for adding your own content to the Remarks section of these pages. - -'''The Remarks section provides additional information related to other sections on the page as well as a location for users to add comments related to real-world application of the API.''' - - - -== General Guidelines == - -'''Please post appropriate remarks that may benefit other users.''' -* Do not post anything that you do not have permission to post publicly. -* Remarks should have adequate references to make them clear and useful. -* Please remember to keep it accurate, simple, and easy to understand. -* ''Important!'' The Remarks section is not a discussion board. This is not an appropriate place to post questions, unrelated comments, or general commentary. Only constructive information is to be posted in the Remarks section. -: Please use the [http://forums.libsdl.org/ forums], [http://www.libsdl.org/mailing-list.php mailing lists], ''Feedback'' form (upper right corner), or email (<>) if you have questions or need to discuss some aspect of the API. - -~-[[#ToC|Return to Table of Contents]]-~ - -== Adding Your Remarks == - 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 that begins with ```== Remarks ==```. Add your content below this heading following the conventions in this style guide. - 1. Find information relevant to your content in the style guide sections [[#formatting|below]] and apply the appropriate formatting as you create your content. - 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 [[SGWikiBasics#color2|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 additional assistance with editing, saving, or wiki-appropriate markup see the [[SGWikiBasics|Wiki Basics]] Style Guide. - - -~-[[#ToC|Return to Table of Contents]]-~ -
- -== Formatting Your Remarks == - -=== Location === -{| -|<( |2 30%>''If'' your remark is the __first on the page__ -|''Action'': Replace the following text and markup with your remarks:
```''You can add useful comments here''``` -|- -|''Example'': [[SDL_StopTextInput]]()
~-(Remarks were empty at the time this was selected.-~) -|- -|<( |3>''If'' there are __existing remarks__ on the page -|''Action'': Add your remarks to the end of the Remarks section, or to a related grouping if there are existing remarks covering the same topic. -|- -|''Important!'' Do not change or remove any of the existing content. -|- -|''Example'': [[SDL_MixAudio]]() -|} - -~-[[#ToC|Return to Table of Contents]]-~ - - -=== Referencing Function Parameters === -When your remark includes a reference to a function parameter: -{| -|<( |3 30%>''If'' you are referencing a parameter __on the same page__ -|''Action'': Use '''bold''' wherever the name is used in the remark. -|- -|''Markup'': Use 3 apostrophes on either side of the text for bold.
```'''parameter'''``` = '''parameter''' -|- -|''Example'': [[SDL_ConvertAudio]]() -|- -|<( |3>''If'' you are referencing a parameter __from another page__ -|''Action'': Use monospace wherever the name is used in the remark. -|- -|''Markup'': Use a single backtick on either side of the text for monospace.
```member``` = member -|- -|''Example'': [[SDL_OpenAudio]]() -|} - -~-[[#ToC|Return to Table of Contents]]-~ - -=== Referencing Structure Data Fields === -''If'' your remark includes a reference to a structure data field: - -''Action'': Use the same formatting as for [[#params|function parameters]] above. - -''Example'': [[SDL_AudioSpec]] - -~-[[#ToC|Return to Table of Contents]]-~ - -=== Referencing Enumeration Values === -''If'' your remark includes a reference to an enumeration value: - -''Action'': No special formatting is required since these are generally already in ALL CAPS. - -''Example'': [[SDL_GLattr]] - -~-[[#ToC|Return to Table of Contents]]-~ - -=== Referencing A Callback Function === -''If'' your remark is describing a callback function: - -''Action'': See the special section on callback functions in the [[SGFunctions#Callback_Functions|Function Pages]] Style Guide. - -''Note'': Callback functions do not get their own pages. - -''Example'': [[SDL_AddEventWatch]](), [[SDL_AddTimer]]() - -~-[[#ToC|Return to Table of Contents]]-~ - -=== Using an Include === -''If'' your remark uses an [[SGWikiBasics#Includes|Include]] to copy content from another page into the Remarks section, see the guidelines below. - -{| -|<( 30%>''If'' your Include is copying __stand-alone content__ into the Remarks -|''Action'': A tie-in statement is not likely necessary. In that case, simply follow the instructions for creating an Include in [[SGWikiBasics#Includes|Wiki Basics]] -|- -|<( |2 30%>''If'' your Include is used to copy __values from a related enumeration__ that was mentioned in the Function Parameters section (''most common use'') -|''Action'': See the following table for tie-in text options to precede the [[SGWikiBasics#Includes|Include]]. -|- -|''Note'': In these examples, replace with the relevant parameter name and replace with the name of the enumeration or other page being referenced. -|- -|<( 30%>''If'' your Include is for __some other purpose__ -|''Action'': Please apply the closest appropriate match from the other two options (above) with minimal modifications, or contact us if you are unsure what to do. -|} - -''Action'': If required (see table above), select from the following introductory phrases to explain the relationship of the included material to the page: - -{| -|<( |2 30%>''If'' the Include contains a list from which __only one option__ may be selected -|''Action'': Place the following phrase on the line above the Include markup
''''''may be one of the following: -|- -|''Example'': [[SDL_CreateTexture]](), [[SDL_SetThreadPriority]]() -|- -|<( |2 30%>''If'' the Include contains a list from which __more than one option__ may be selected -|''Action'': Place the following phrase on the line above the Include markup
'''''' may be any of the following OR'd together: -|- -|''Example'': [[SDL_CreateRenderer]]() -|- -|<( |2 30%>''If'' the Include contains a list from which __only one value will be used to fill a parameter__ -|''Action'': Place the following phrase on the line above the Include markup
'''parameter''' will be filled in with one of the following: -|- -|''Example'': [[SDL_GetTextureBlendMode]]() -|- -|<( |2 30%>''If'' the Include contains a list from which __more than one option may be selected or the value may be 0__ -|''Action'': Place the following phrase on the line above the Include markup
'''parameter''' may be 0 or a mask of any of the following SDL_ values OR'd together: -|- -|''Example'': [[SDL_RendererInfo]] -|- -|<( |2 30%>''If'' the Include contains a list from which __one or more than one__ option may be selected -|''Action'': Place the following phrase on the line above the Include markup
'''parameter''' may be