mirror of
https://github.com/VARCem/PDCurses.git
synced 2026-09-24 15:55:14 +00:00
Update SDL2 documentation
This commit is contained in:
Robin Gustafsson
58
doc/sdl2.md
Normal file
58
doc/sdl2.md
Normal file
@@ -0,0 +1,58 @@
|
||||
SDL2 Considerations
|
||||
===================
|
||||
|
||||
Most of the information in the [SDL Considerations](sdl.md) document is also
|
||||
valid for the SDL2 platform. This document describes the differences.
|
||||
|
||||
|
||||
Integration with SDL2
|
||||
---------------------
|
||||
|
||||
As mentioned in the [SDL Considerations](sdl.md) document, the SDL port uses
|
||||
the following variables:
|
||||
|
||||
SDL_Surface *pdc_screen, *pdc_font, *pdc_icon, *pdc_back;
|
||||
int pdc_sheight, pdc_swidth, pdc_yoffset, pdc_xoffset;
|
||||
|
||||
The SDL2 port adds:
|
||||
|
||||
SDL_Window *pdc_window;
|
||||
|
||||
These can be used or modified in your own code. Like the `pdc_screen` variable
|
||||
used by the SDL port, you can initialize `pdc_window` in your own code. See the
|
||||
sdltest demo for an example. If it's not initialized, PDCurses will do it for
|
||||
you. If PDCurses initializes `pdc_window`, it will clean up/deallocate these
|
||||
variables on exit.
|
||||
|
||||
|
||||
Fonts
|
||||
-----
|
||||
|
||||
If the `PDC_WIDE` flag is set during compilation, SDL2_ttf is used to render
|
||||
fonts. This allows for use of a full UCS-2 (16 bit Unicode) character set.
|
||||
|
||||
Using SDL2_ttf adds:
|
||||
|
||||
TTF_Font *pdc_ttffont;
|
||||
int pdc_font_size;
|
||||
|
||||
The default TrueType font can be modified by setting a define during compile
|
||||
time (e.g. `-DPDC_FONT_PATH=/usr/share/fonts/truetype/dejavu/`). This can be
|
||||
overridden by initializing `pdc_ttffont` in your own code. Similar
|
||||
to the `PDC_FONT` environment variable for bitmap fonts, one can also override
|
||||
TTF fonts using the `PDC_FONT` environment variables. Unless modified during
|
||||
compile time, the defaults are:
|
||||
|
||||
Windows: C:/Windows/Fonts/lucon.ttf
|
||||
OS X: /Library/Fonts/Courier New.ttf
|
||||
Other: /usr/share/fonts/truetype/freefont/FreeMono.ttf
|
||||
|
||||
Font size can be set using the `PDC_FONT_SIZE` environment variable or by
|
||||
setting the value of `pdc_font_size` in your own code. The default size is 18.
|
||||
|
||||
|
||||
Clipboard
|
||||
---------
|
||||
|
||||
SDL2 port uses functionality provided by the SDL2 clipboard functions to add
|
||||
basic clipboard support.
|
||||
100
doc/sdl2.txt
100
doc/sdl2.txt
@@ -1,100 +0,0 @@
|
||||
SDL2 Considerations
|
||||
===================
|
||||
|
||||
Clipboard
|
||||
---------
|
||||
|
||||
SDL2 port uses functionality provided by the SDL2 clipboard functions to add
|
||||
basic clipboard support.
|
||||
|
||||
|
||||
Fonts
|
||||
-----
|
||||
|
||||
If the PDC_WIDE flag is set, SDL2 version uses SDL2_ttf and SDL version
|
||||
uses SDL_ttf to render fonts. This allows for use of a full UCS-2 (16 bit
|
||||
Unicode) character set.
|
||||
|
||||
SDL2 has several changes from SDL on how to handle Unicode character input
|
||||
including the addition of SDL_TEXTINPUT event and new functions to use with it.
|
||||
This allows use of an input method editor to enter characters that may not be
|
||||
standard for the keyboard. For simplicity, the pdcurses SDL_ttf additions
|
||||
don't use this new added functionality. They take an approach that will work
|
||||
with SDL or SDL2. Windows users may be familiar with holding down the alt key
|
||||
while entering a numeric value via the keypad. Windows translates this input
|
||||
and the number into a character. The SDL ports with PDC_WIDE option use a
|
||||
similar technique across all platforms not just Windows.
|
||||
|
||||
To enter a hexidecimal value for a character, hold down the alt key and press
|
||||
plus on the numeric keypad. Then, enter the hexidecimal code for the
|
||||
character. Then, release the alt key. To enter a decimal number, hold down
|
||||
the alt key and press 0 on the keypad, followed by the decimal equivalent of
|
||||
the character. Release the alt key. This allows users to enter characters not
|
||||
available on their keyboards without need for additional code or programs to
|
||||
deal with input.
|
||||
|
||||
The default Truetype font used is a monospaced font. One can specify another
|
||||
font using the integration methods described. The font does not necessarily
|
||||
need to be a monospaced font. Since PDCurses assumes a fixed size (default
|
||||
screen size is 80x25), a monospaced font may look better on screen than other
|
||||
types of fonts.
|
||||
|
||||
|
||||
Integration with SDL2 and SDL2_TTF or SDL_TTF
|
||||
---------------------------------------------
|
||||
|
||||
As mentioned in SDL Considerations document, the SDL port uses the following
|
||||
variables:
|
||||
|
||||
PDCEX SDL_Surface *pdc_screen, *pdc_font, *pdc_icon, *pdc_back;
|
||||
PDCEX int pdc_sheight, pdc_swidth, pdc_yoffset, pdc_xoffset;
|
||||
|
||||
The SDL2 port adds:
|
||||
|
||||
SDL_Window *pdc_window;
|
||||
|
||||
Using SDL_ttf (with SDL2 or SDL) adds:
|
||||
|
||||
TTF_Font *pdc_ttffont;
|
||||
SDL_Color *pdc_ttffont_foregroundcolor;
|
||||
SDL_Color *pdc_ttffont_backgroundcolor;
|
||||
int pdc_ttffont_spointsz;
|
||||
int pdc_ttffont_hint;
|
||||
|
||||
These can be used or modified in your own code. Like the pdc_screen variable
|
||||
used by the SDL port, you can initialize pdc_window in your own code. If it's
|
||||
not initialized, PDCurses will do it for you. See the sdltest demo for an
|
||||
example. If PDCurses is built with the PDC_WIDE flag, it will clean up/
|
||||
deallocate these variables on exit when needed.
|
||||
|
||||
Default font for SDL_TTF is assumed to be DejaVuSansMono.ttf from the Open
|
||||
Source DejaVu fonts. The code looks for this font to already be installed in
|
||||
a standard directory (based on the Filesystem Hierarchy Standard)
|
||||
/usr/local/share/fonts/truetype/dejavu/. This can be modified by setting a
|
||||
define during compile time
|
||||
( -DPDC_FONT_PATH=/usr/share/fonts/truetype/dejavu/ ) This can be overridden
|
||||
by initializing pdc_ttffont in your own code. Similar to the
|
||||
PDC_FONT environment variable for SDL bitmap fonts, one can also override TTF
|
||||
fonts using the PDC_FONT and PDC_FONT_POINT_SIZE environment variables.
|
||||
|
||||
How a font is rendered on the screen depends on a number of factors.
|
||||
TTF_SetFontHinting (from SDL_TTF or SDL2_TTF) uses the pdc_ttffont_hint setting
|
||||
which can affect how the font appears on the screen. Default for PDCurses is
|
||||
currently TTF_HINTING_MONO, but one can also use TTF_HINTING_NORMAL,
|
||||
TTF_HINTING_LIGHT, TTF_HINTING_NONE by setting pdc_ttffont_hint before
|
||||
PDCurses initializes pdc_ttffont. If you initialize pdc_ttffont in your own
|
||||
code, TTF_SetFontHinting is not called by PDCurses and the default setting is
|
||||
TTF_HINTING_NORMAL. This can always be changed in your own code by calling
|
||||
TTF_SetFontHinting. The font is also affected by the settings used when
|
||||
building the freetype library (which SDL_TTF or SDL2_TTF uses). For example,
|
||||
on Windows, one may want to add the following compile time flags when building
|
||||
the freetype library:
|
||||
-DTT_CONFIG_OPTION_SUBPIXEL_HINTING -DFT_CONFIG_OPTION_SUBPIXEL_RENDERING
|
||||
Some testing was done building freetype with and without harfbuzz library and
|
||||
that did not seem to affect TTF rendering. (Harfbuzz mainly relates to
|
||||
OpenType fonts, OTF rendering.)
|
||||
|
||||
|
||||
SDL2 and SDL_TTF modifications were added by Laura Michaels in 2015.
|
||||
SDL2 and SDL_TTF modifications are licensed using the Creative Commons license
|
||||
CC0 ( https://creativecommons.org/publicdomain/zero/1.0/ ).
|
||||
33
sdl2/README
33
sdl2/README
@@ -1,33 +0,0 @@
|
||||
PDCurses for SDL
|
||||
================
|
||||
|
||||
This is a port of PDCurses for SDL.
|
||||
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
. On *nix (including Linux and Mac OS X), run "make" in the sdl1
|
||||
directory. There is no configure script (yet?) for this port. This
|
||||
assumes a working sdl-config, and GNU make. It builds the library
|
||||
libpdcurses.a (dynamic lib not implemented).
|
||||
|
||||
With MinGW, run "make -f Makefile.mng". This assumes SDL is installed
|
||||
in the standard directories. The MinGW makefile accepts the optional
|
||||
parameters "DLL=Y" and "DEBUG=Y", as with the console version. (Wide-
|
||||
character support is not yet implemented for SDL.) Both makefiles
|
||||
recognize the optional PDCURSES_SRCDIR environment variable, as with
|
||||
the console ports. Makefile.mng builds libpdcurses.a, along with
|
||||
pdcurses.dll, if specified.
|
||||
|
||||
|
||||
Distribution Status
|
||||
-------------------
|
||||
|
||||
The files in this directory are released to the Public Domain.
|
||||
|
||||
|
||||
Acknowledgements
|
||||
----------------
|
||||
|
||||
SDL port was provided by William McBrine <wmcbrine@users.sf.net>
|
||||
29
sdl2/README.md
Normal file
29
sdl2/README.md
Normal file
@@ -0,0 +1,29 @@
|
||||
PDCurses for SDL2
|
||||
=================
|
||||
|
||||
This is a port of PDCurses for SDL2.
|
||||
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
- On *nix (including Linux and Mac OS X), run `make` in the sdl2
|
||||
directory. It builds the library libpdcurses.a (dynamic lib not implemented).
|
||||
The makefile accepts the optional parameters `DEBUG=Y`, `WIDE=Y` and `UTF8=Y`.
|
||||
It also recognizes the optional `PDCURSES_SRCDIR` environment variable.
|
||||
|
||||
|
||||
Distribution Status
|
||||
-------------------
|
||||
|
||||
The files in this directory are released to the Public Domain.
|
||||
|
||||
|
||||
Acknowledgements
|
||||
----------------
|
||||
|
||||
The original SDL port was provided by William McBrine.
|
||||
|
||||
The initial SDL2 support patch was created by Laura Michaels.
|
||||
|
||||
The SDL2 port was put together and further developed by Robin Gustafsson.
|
||||
@@ -6,45 +6,48 @@
|
||||
|
||||
/*man-start**************************************************************
|
||||
|
||||
Name: clipboard
|
||||
clipboard
|
||||
---------
|
||||
|
||||
Synopsis:
|
||||
int PDC_getclipboard(char **contents, long *length);
|
||||
int PDC_setclipboard(const char *contents, long length);
|
||||
int PDC_freeclipboard(char *contents);
|
||||
int PDC_clearclipboard(void);
|
||||
### Synopsis
|
||||
|
||||
Description:
|
||||
PDC_getclipboard() gets the textual contents of the system's
|
||||
clipboard. This function returns the contents of the clipboard
|
||||
in the contents argument. It is the responsibilitiy of the
|
||||
caller to free the memory returned, via PDC_freeclipboard().
|
||||
The length of the clipboard contents is returned in the length
|
||||
argument.
|
||||
int PDC_getclipboard(char **contents, long *length);
|
||||
int PDC_setclipboard(const char *contents, long length);
|
||||
int PDC_freeclipboard(char *contents);
|
||||
int PDC_clearclipboard(void);
|
||||
|
||||
PDC_setclipboard copies the supplied text into the system's
|
||||
clipboard, emptying the clipboard prior to the copy.
|
||||
### Description
|
||||
|
||||
PDC_clearclipboard() clears the internal clipboard.
|
||||
PDC_getclipboard() gets the textual contents of the system's
|
||||
clipboard. This function returns the contents of the clipboard
|
||||
in the contents argument. It is the responsibilitiy of the
|
||||
caller to free the memory returned, via PDC_freeclipboard().
|
||||
The length of the clipboard contents is returned in the length
|
||||
argument.
|
||||
|
||||
Return Values:
|
||||
indicator of success/failure of call.
|
||||
PDC_CLIP_SUCCESS the call was successful
|
||||
PDC_CLIP_MEMORY_ERROR unable to allocate sufficient memory for
|
||||
the clipboard contents
|
||||
PDC_CLIP_EMPTY the clipboard contains no text
|
||||
PDC_CLIP_ACCESS_ERROR no clipboard support
|
||||
PDC_setclipboard copies the supplied text into the system's
|
||||
clipboard, emptying the clipboard prior to the copy.
|
||||
|
||||
Portability X/Open BSD SYS V
|
||||
PDC_getclipboard - - -
|
||||
PDC_setclipboard - - -
|
||||
PDC_freeclipboard - - -
|
||||
PDC_clearclipboard - - -
|
||||
PDC_clearclipboard() clears the internal clipboard.
|
||||
|
||||
### Return Values
|
||||
|
||||
indicator of success/failure of call.
|
||||
PDC_CLIP_SUCCESS the call was successful
|
||||
PDC_CLIP_MEMORY_ERROR unable to allocate sufficient memory for
|
||||
the clipboard contents
|
||||
PDC_CLIP_EMPTY the clipboard contains no text
|
||||
PDC_CLIP_ACCESS_ERROR no clipboard support
|
||||
|
||||
### Portability
|
||||
X/Open BSD SYS V
|
||||
PDC_getclipboard - - -
|
||||
PDC_setclipboard - - -
|
||||
PDC_freeclipboard - - -
|
||||
PDC_clearclipboard - - -
|
||||
|
||||
**man-end****************************************************************/
|
||||
|
||||
/* global clipboard contents, should be NULL if none set */
|
||||
|
||||
int PDC_getclipboard(char **contents, long *length)
|
||||
{
|
||||
PDC_LOG(("PDC_getclipboard() - called\n"));
|
||||
|
||||
@@ -4,17 +4,21 @@
|
||||
|
||||
/*man-start**************************************************************
|
||||
|
||||
Name: pdckbd
|
||||
pdckbd
|
||||
------
|
||||
|
||||
Synopsis:
|
||||
unsigned long PDC_get_input_fd(void);
|
||||
### Synopsis
|
||||
|
||||
Description:
|
||||
PDC_get_input_fd() returns the file descriptor that PDCurses
|
||||
reads its input from. It can be used for select().
|
||||
unsigned long PDC_get_input_fd(void);
|
||||
|
||||
Portability X/Open BSD SYS V
|
||||
PDC_get_input_fd - - -
|
||||
### Description
|
||||
|
||||
PDC_get_input_fd() returns the file descriptor that PDCurses
|
||||
reads its input from. It can be used for select().
|
||||
|
||||
### Portability
|
||||
X/Open BSD SYS V
|
||||
PDC_get_input_fd - - -
|
||||
|
||||
**man-end****************************************************************/
|
||||
|
||||
|
||||
@@ -4,28 +4,32 @@
|
||||
|
||||
/*man-start**************************************************************
|
||||
|
||||
Name: pdcsetsc
|
||||
pdcsetsc
|
||||
--------
|
||||
|
||||
Synopsis:
|
||||
int PDC_set_blink(bool blinkon);
|
||||
void PDC_set_title(const char *title);
|
||||
### Synopsis
|
||||
|
||||
Description:
|
||||
PDC_set_blink() toggles whether the A_BLINK attribute sets an
|
||||
actual blink mode (TRUE), or sets the background color to high
|
||||
intensity (FALSE). The default is platform-dependent (FALSE in
|
||||
most cases). It returns OK if it could set the state to match
|
||||
the given parameter, ERR otherwise. Current platforms also
|
||||
adjust the value of COLORS according to this function -- 16 for
|
||||
FALSE, and 8 for TRUE.
|
||||
int PDC_set_blink(bool blinkon);
|
||||
void PDC_set_title(const char *title);
|
||||
|
||||
PDC_set_title() sets the title of the window in which the curses
|
||||
program is running. This function may not do anything on some
|
||||
platforms. (Currently it only works in Win32 and X11.)
|
||||
### Description
|
||||
|
||||
Portability X/Open BSD SYS V
|
||||
PDC_set_blink - - -
|
||||
PDC_set_title - - -
|
||||
PDC_set_blink() toggles whether the A_BLINK attribute sets an
|
||||
actual blink mode (TRUE), or sets the background color to high
|
||||
intensity (FALSE). The default is platform-dependent (FALSE in
|
||||
most cases). It returns OK if it could set the state to match
|
||||
the given parameter, ERR otherwise. Current platforms also
|
||||
adjust the value of COLORS according to this function -- 16 for
|
||||
FALSE, and 8 for TRUE.
|
||||
|
||||
PDC_set_title() sets the title of the window in which the curses
|
||||
program is running. This function may not do anything on some
|
||||
platforms. (Currently it only works in Win32 and X11.)
|
||||
|
||||
### Portability
|
||||
X/Open BSD SYS V
|
||||
PDC_set_blink - - -
|
||||
PDC_set_title - - -
|
||||
|
||||
**man-end****************************************************************/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user