From 586d3bfca7681dc8120d2f2005410a1b9b2e7f73 Mon Sep 17 00:00:00 2001 From: Robin Gustafsson Date: Sat, 19 Nov 2016 01:19:27 +0100 Subject: [PATCH] Update SDL2 documentation --- doc/sdl2.md | 58 ++++++++++++++++++++++++++++ doc/sdl2.txt | 100 ------------------------------------------------ sdl2/README | 33 ---------------- sdl2/README.md | 29 ++++++++++++++ sdl2/pdcclip.c | 63 +++++++++++++++--------------- sdl2/pdckbd.c | 20 ++++++---- sdl2/pdcsetsc.c | 40 ++++++++++--------- 7 files changed, 154 insertions(+), 189 deletions(-) create mode 100644 doc/sdl2.md delete mode 100644 doc/sdl2.txt delete mode 100644 sdl2/README create mode 100644 sdl2/README.md diff --git a/doc/sdl2.md b/doc/sdl2.md new file mode 100644 index 00000000..c2dd8a63 --- /dev/null +++ b/doc/sdl2.md @@ -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. diff --git a/doc/sdl2.txt b/doc/sdl2.txt deleted file mode 100644 index 0770b53b..00000000 --- a/doc/sdl2.txt +++ /dev/null @@ -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/ ). diff --git a/sdl2/README b/sdl2/README deleted file mode 100644 index 213d23f6..00000000 --- a/sdl2/README +++ /dev/null @@ -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 diff --git a/sdl2/README.md b/sdl2/README.md new file mode 100644 index 00000000..db67b743 --- /dev/null +++ b/sdl2/README.md @@ -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. diff --git a/sdl2/pdcclip.c b/sdl2/pdcclip.c index d09b84ef..fb0035c2 100644 --- a/sdl2/pdcclip.c +++ b/sdl2/pdcclip.c @@ -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")); diff --git a/sdl2/pdckbd.c b/sdl2/pdckbd.c index c5449c91..3af2fa50 100644 --- a/sdl2/pdckbd.c +++ b/sdl2/pdckbd.c @@ -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****************************************************************/ diff --git a/sdl2/pdcsetsc.c b/sdl2/pdcsetsc.c index 5e6ce177..4ebbd4d4 100644 --- a/sdl2/pdcsetsc.c +++ b/sdl2/pdcsetsc.c @@ -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****************************************************************/