admin/CSFML
1
0 Fork 0
mirror of https://github.com/SFML/CSFML.git synced 2026-10-26 21:16:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improved API documentation (copied from SFML)

Browse Source
This commit is contained in:
Laurent Gomila committed 2011-09-02 20:15:45 +02:00
1 parent c84a787d0a
commit d734c9df5c
50 files changed
+1606 -1478
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

include/SFML/Window/Window.h
+184 -80
View File
@@ -36,7 +36,7 @@
////////////////////////////////////////////////////////////
/// Enumeration of window creation styles
/// \brief Enumeration of window creation styles
///
////////////////////////////////////////////////////////////
enum
@@ -51,7 +51,8 @@ enum
////////////////////////////////////////////////////////////
/// Structure defining the window's creation settings
/// \brief Structure defining the window's creation settings
///
////////////////////////////////////////////////////////////
typedef struct
{
@@ -64,53 +65,89 @@ typedef struct
////////////////////////////////////////////////////////////
/// Construct a new window
/// \brief Construct a new window
///
/// \param mode : Video mode to use
/// \param title : Title of the window
/// \param style : Window style
/// \param settings : Creation settings (pass NULL to use default values)
/// This function creates the window with the size and pixel
/// depth defined in \a mode. An optional style can be passed to
/// customize the look and behaviour of the window (borders,
/// title bar, resizable, closable, ...). If \a style contains
/// sfFullscreen, then \a mode must be a valid video mode.
///
/// The fourth parameter is a pointer to a structure specifying
/// advanced OpenGL context settings such as antialiasing,
/// depth-buffer bits, etc.
///
/// \param mode Video mode to use (defines the width, height and depth of the rendering area of the window)
/// \param title Title of the window
/// \param style Window style
/// \param settings Additional settings for the underlying OpenGL context
///
/// \return A new sfWindow object
///
////////////////////////////////////////////////////////////
CSFML_API sfWindow* sfWindow_Create(sfVideoMode mode, const char* title, unsigned long style, const sfContextSettings* settings);
////////////////////////////////////////////////////////////
/// Construct a window from an existing control
/// \brief Construct a window from an existing control
///
/// \param handle : Platform-specific handle of the control
/// \param settings : Creation settings (pass NULL to use default values)
/// Use this constructor if you want to create an OpenGL
/// rendering area into an already existing control.
///
/// The second parameter is a pointer to a structure specifying
/// advanced OpenGL context settings such as antialiasing,
/// depth-buffer bits, etc.
///
/// \param handle Platform-specific handle of the control
/// \param settings Additional settings for the underlying OpenGL context
///
/// \return A new sfWindow object
///
////////////////////////////////////////////////////////////
CSFML_API sfWindow* sfWindow_CreateFromHandle(sfWindowHandle handle, const sfContextSettings* settings);
////////////////////////////////////////////////////////////
/// Destroy an existing window
/// \brief Destroy a window
///
/// \param window : Window to destroy
/// \param window Window to destroy
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_Destroy(sfWindow* window);
////////////////////////////////////////////////////////////
/// Close a window (but doesn't destroy the internal data)
/// \brief Close a window and destroy all the attached resources
///
/// \param window : Window to close
/// After calling this function, the sfWindow object remains
/// valid, you must call sfWindow_Destroy to actually delete it.
/// All other functions such as sfWindow_PollEvent or sfWindow_Display
/// will still work (i.e. you don't have to test sfWindow_IsOpened
/// every time), and will have no effect on closed windows.
///
/// \param window Window object
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_Close(sfWindow* window);
////////////////////////////////////////////////////////////
/// Tell whether or not a window is opened
/// \brief Tell whether or not a window is opened
///
/// \param window : Window object
/// This function returns whether or not the window exists.
/// Note that a hidden window (sfWindow_Show(sfFalse)) will return
/// sfTrue.
///
/// \param window Window object
///
/// \return sfTrue if the window is opened, sfFalse if it has been closed
///
////////////////////////////////////////////////////////////
CSFML_API sfBool sfWindow_IsOpened(const sfWindow* window);
////////////////////////////////////////////////////////////
/// Get the width of the rendering region of a window
/// \brief Get the width of the rendering region of a window
///
/// \param window : Window object
/// The width doesn't include the titlebar and borders
/// of the window.
///
/// \param window Window object
///
/// \return Width in pixels
///
@@ -118,9 +155,12 @@ CSFML_API sfBool sfWindow_IsOpened(const sfWindow* window);
CSFML_API unsigned int sfWindow_GetWidth(const sfWindow* window);
////////////////////////////////////////////////////////////
/// Get the height of the rendering region of a window
/// \brief Get the height of the rendering region of a window
///
/// \param window : Window object
/// The height doesn't include the titlebar and borders
/// of the window.
///
/// \param window Window object
///
/// \return Height in pixels
///
@@ -128,169 +168,233 @@ CSFML_API unsigned int sfWindow_GetWidth(const sfWindow* window);
CSFML_API unsigned int sfWindow_GetHeight(const sfWindow* window);
////////////////////////////////////////////////////////////
/// Get the creation settings of a window
/// \brief Get the settings of the OpenGL context of a window
///
/// \param window : Window object
/// Note that these settings may be different from what was
/// passed to the sfWindow_Create function,
/// if one or more settings were not supported. In this case,
/// SFML chose the closest match.
///
/// \return Settings used to create the window
/// \param window Window object
///
/// \return Structure containing the OpenGL context settings
///
////////////////////////////////////////////////////////////
CSFML_API sfContextSettings sfWindow_GetSettings(const sfWindow* window);
////////////////////////////////////////////////////////////
/// Get the event on top of events stack of a window, if any, and pop it
/// \brief Pop the event on top of events stack, if any, and return it
///
/// \param window : Window object
/// \param event : Event to fill, if any
/// This function is not blocking: if there's no pending event then
/// it will return false and leave \a event unmodified.
/// Note that more than one event may be present in the events stack,
/// thus you should always call this function in a loop
/// to make sure that you process every pending event.
///
/// \return sfTrue if an event was returned, sfFalse if events stack was empty
/// \param window Window object
/// \param event Event to be returned
///
/// \return sfTrue if an event was returned, or sfFalse if the events stack was empty
///
////////////////////////////////////////////////////////////
CSFML_API sfBool sfWindow_PollEvent(sfWindow* window, sfEvent* event);
////////////////////////////////////////////////////////////
/// Wait for an event and return it
/// \brief Wait for an event and return it
///
/// \param window : Window object
/// \param event : Event to fill
/// This function is blocking: if there's no pending event then
/// it will wait until an event is received.
/// After this function returns (and no error occured),
/// the \a event object is always valid and filled properly.
/// This function is typically used when you have a thread that
/// is dedicated to events handling: you want to make this thread
/// sleep as long as no new event is received.
///
/// \return sfFalse if an error occured
/// \param window Window object
/// \param event Event to be returned
///
/// \return sfFalse if any error occured
///
////////////////////////////////////////////////////////////
CSFML_API sfBool sfWindow_WaitEvent(sfWindow* window, sfEvent* event);
////////////////////////////////////////////////////////////
/// Enable / disable vertical synchronization on a window
/// \brief Enable or disable vertical synchronization
///
/// \param window : Window object
/// \param enabled : sfTrue to enable v-sync, sfFalse to deactivate
/// Activating vertical synchronization will limit the number
/// of frames displayed to the refresh rate of the monitor.
/// This can avoid some visual artifacts, and limit the framerate
/// to a good value (but not constant across different computers).
///
/// \param window Window object
/// \param enabled sfTrue to enable v-sync, sfFalse to deactivate
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_EnableVerticalSync(sfWindow* window, sfBool enabled);
////////////////////////////////////////////////////////////
/// Show or hide the mouse cursor on a window
/// \brief Show or hide the mouse cursor
///
/// \param window : Window object
/// \param show : sfTrue to show, sfFalse to hide
/// \param window Window object
/// \param show sfTrue to show, sfFalse to hide
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_ShowMouseCursor(sfWindow* window, sfBool show);
////////////////////////////////////////////////////////////
/// Change the position of a window on screen.
/// Only works for top-level windows
/// \brief Change the position of a window on screen
///
/// \param window : Window object
/// \param left : Left position
/// \param top : Top position
/// This function only works for top-level windows
/// (i.e. it will be ignored for windows created from
/// the handle of a child window/control).
///
/// \param window Window object
/// \param x Left position
/// \param y Top position
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_SetPosition(sfWindow* window, int left, int top);
////////////////////////////////////////////////////////////
/// Change the size of the rendering region of a window
/// \brief Change the size of the rendering region of a window
///
/// \param window : Window object
/// \param width : New Width
/// \param height : New Height
/// \param window Window object
/// \param width New width, in pixels
/// \param height New height, in pixels
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_SetSize(sfWindow* window, unsigned int width, unsigned int height);
////////////////////////////////////////////////////////////
/// Change the title of a window
/// \brief Change the title of a window
///
/// \param window : Window object
/// \param title : New title
/// \param window Window object
/// \param title New title
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_SetTitle(sfWindow* window, const char* title);
////////////////////////////////////////////////////////////
/// Show or hide a window
/// \brief Show or hide a window
///
/// \param window : Window object
/// \param show : sfTrue to show, sfFalse to hide
/// \param window Window object
/// \param show sfTrue to show, sfFalse to hide
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_Show(sfWindow* window, sfBool show);
////////////////////////////////////////////////////////////
/// Enable or disable automatic key-repeat for keydown events.
/// Automatic key-repeat is enabled by default
/// \brief Enable or disable automatic key-repeat
///
/// \param window : Window object
/// \param enabled : sfTrue to enable, sfFalse to disable
/// If key repeat is enabled, you will receive repeated
/// KeyPress events while keeping a key pressed. If it is disabled,
/// you will only get a single event when the key is pressed.
///
/// Key repeat is enabled by default.
///
/// \param window Window object
/// \param enabled sfTrue to enable, sfFalse to disable
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_EnableKeyRepeat(sfWindow* window, sfBool enabled);
////////////////////////////////////////////////////////////
/// Change the window's icon
/// \brief Change a window's icon
///
/// \param window : Window object
/// \param width : Icon's width, in pixels
/// \param height : Icon's height, in pixels
/// \param pixels : Pointer to the pixels in memory, format must be RGBA 32 bits
/// \a pixels must be an array of \a width x \a height pixels
/// in 32-bits RGBA format.
///
/// \param window Window object
/// \param width Icon's width, in pixels
/// \param height Icon's height, in pixels
/// \param pixels Pointer to the array of pixels in memory
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_SetIcon(sfWindow* window, unsigned int width, unsigned int height, const sfUint8* pixels);
////////////////////////////////////////////////////////////
/// Activate or deactivate a window as the current target for rendering
/// \brief Activate or deactivate a window as the current target
/// for OpenGL rendering
///
/// \param window : Window object
/// \param active : sfTrue to activate, sfFalse to deactivate
/// A window is active only on the current thread, if you want to
/// make it active on another thread you have to deactivate it
/// on the previous thread first if it was active.
/// Only one window can be active on a thread at a time, thus
/// the window previously active (if any) automatically gets deactivated.
///
/// \return True if operation was successful, false otherwise
/// \param window Window object
/// \param active sfTrue to activate, sfFalse to deactivate
///
/// \return sfTrue if operation was successful, sfFalse otherwise
///
////////////////////////////////////////////////////////////
CSFML_API sfBool sfWindow_SetActive(sfWindow* window, sfBool active);
////////////////////////////////////////////////////////////
/// Display a window on screen
/// \brief Display on screen what has been rendered to the
/// window so far
///
/// \param window : Window object
/// This function is typically called after all OpenGL rendering
/// has been done for the current frame, in order to show
/// it on screen.
///
/// \param window Window object
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_Display(sfWindow* window);
////////////////////////////////////////////////////////////
/// Limit the framerate to a maximum fixed frequency for a window
/// \brief Limit the framerate to a maximum fixed frequency
///
/// \param window : Window object
/// \param limit : Framerate limit, in frames per seconds (use 0 to disable limit)
/// If a limit is set, the window will use a small delay after
/// each call to sfWindow_Display to ensure that the current frame
/// lasted long enough to match the framerate limit.
///
/// \param window Window object
/// \param limit Framerate limit, in frames per seconds (use 0 to disable limit)
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_SetFramerateLimit(sfWindow* window, unsigned int limit);
////////////////////////////////////////////////////////////
/// Get time elapsed since last frame of a window
/// \brief Get the duration of the last frame
///
/// \param window : Window object
/// This function returns the time elapsed between the last
/// two calls to sfWindow_Display.
/// This can be useful for calculating the framerate, or for
/// updating the application's objects.
///
/// \return Time elapsed, in milliseconds
/// \param window Window object
///
/// \return Time elapsed in last frame, in milliseconds
///
////////////////////////////////////////////////////////////
CSFML_API sfUint32 sfWindow_GetFrameTime(const sfWindow* window);
////////////////////////////////////////////////////////////
/// Change the joystick threshold, ie. the value below which
/// no move event will be generated
/// \brief Change the joystick threshold
///
/// \param window : Window object
/// \param threshold : New threshold, in range [0, 100]
/// The joystick threshold is the value below which
/// no JoyMoved event will be generated.
///
/// \param window Window object
/// \param threshold New threshold, in the range [0, 100]
///
////////////////////////////////////////////////////////////
CSFML_API void sfWindow_SetJoystickThreshold(sfWindow* window, float threshold);
////////////////////////////////////////////////////////////
/// Retrieve the Os-specific handle of a window
/// \brief Get the OS-specific handle of the window
///
/// \param window : Window object
/// The type of the returned handle is sfWindowHandle,
/// which is a typedef to the handle type defined by the OS.
/// You shouldn't need to use this function, unless you have
/// very specific stuff to implement that SFML doesn't support,
/// or implement a temporary workaround until a bug is fixed.
///
/// \return Window handle
/// \param window Window object
///
/// \return System handle of the window
///
////////////////////////////////////////////////////////////
CSFML_API sfWindowHandle sfWindow_GetSystemHandle(const sfWindow* window);