Add link to project website to README.
[tinyclipboard.git] / README.md
1 tinyclipboard
2 =============
3
4 tinyclipboard is a cross-platform C library for accessing the
5 operating system’s clipboard. It is intended to be as standalone as
6 possible and not depend on any external libraries except those
7 absolutely required for clipboard access (e.g. libX11 for X
8 servers). Especially it is independant from any large GUI toolkit
9 libraries.
10
11 tinyclipboard gives access to read and write text strings from and to
12 the clipboard. Images and other nontextual data formats are not
13 supported.
14
15 The library puts a strong focus on UTF-8 text. Any string you retrieve
16 from the clipboard will be returned to you in UTF-8, and any string
17 you pass is expected to be encoded in UTF-8. Under the hood,
18 tinyclipboard takes care of converting the UTF-8 string into the
19 encoding used by the underlying clipboard system.
20
21 Supported systems
22 -----------------
23
24 These operating systems and graphics stacks are supported currently:
25
26 * Linux systems using X11
27 * Windows
28
29 The library builds natively on Windows with both MinGW and mingw-w64,
30 and I have successfully crosscompiled it from Linux using both
31 toolchains also.
32
33 Building
34 --------
35
36 You can build and use the tinyclipboard library in one of three ways:
37
38 1. Compile and use it as a static library as part of your project
39 (recommended)
40 2. Compile and use it directly in your project
41 3. Compile and use it as a dynamic library
42
43 The tinyclipboard library consists of one header file and one C
44 sourcecode file. It is recommended to build tinyclipboard as part of
45 your project and link it into your executable as a static library
46 (option 1 above). Since it is such a small library, you might also
47 consider to simply drop the two files directly into your project
48 without a separate library step (option 2, see below for more
49 information). Finally, tinyclipboard’s Makefile also builds a dynamic
50 library (option 3).
51
52 To build the static and dynamic library files, issue
53
54 ~~~~~~~~~~~~~~~~~~~~
55 $ make
56 ~~~~~~~~~~~~~~~~~~~~
57
58 in the project directory. You will be left with both a `.a` file
59 (static library) and a `.so` file (dynamic library) in the project
60 root directory.
61
62 If you wish to install the tinyclipboard library to your system
63 instead of building it as part of your project, you can issue the
64 usual
65
66 ~~~~~~~~~~~~~~~~~~~~
67 $ make install
68 ~~~~~~~~~~~~~~~~~~~~
69
70 command. The `install` task understands the usual `PREFIX` and
71 `DESTDIR` variables in case you need them.
72
73 If you want to build the tinyclipboard library as part of your
74 project, simply drop the header and C source code file into your
75 source tree and have your preferred build system compile and link them
76 in. The only thing to consider here is that you need to link in libX11
77 (`-lX11`) when you build your program for an X11 system. If you are
78 building an application with a graphical user interface, chances are
79 high that you need to link in libX11 anyawy.
80
81 Examples
82 --------
83
84 There are some examples of use provided in the `examples/` directory
85 in the source tree. To build them, issue one of:
86
87 ~~~~~~~~~~~~~~~~~~~~
88 $ make examples_x11 # X11 systems
89 $ make examples_win32 # Windows systems
90 ~~~~~~~~~~~~~~~~~~~~
91
92 in the toplevel directory. The different commands are to accomodate
93 the different linking needs (X11 systems need `-lX11` to be linked in).
94
95 Usage
96 -----
97
98 The tinyclipboard library provides three main functions:
99
100 * `tiny_clipread()`, which returns the content of the clipboard.
101 * `tiny_clipwrite()`, which replaces the content of the clipboard.
102 * `tiny_clipnwrite()`, which is the same as `tiny_clipwrite()` with
103 the exception that it allows to embed NUL bytes into the clipboard
104 on X11.
105
106 For version information, the `tiny_clipversion()` function is
107 available.
108
109 Minimal example of how to read from the clipboard:
110
111 ~~~~~~~~~~~~~~~~~~~~ c
112 #include <stdlib.h>
113 #include <stdio.h>
114 #include <tinyclipboard.h>
115
116 int main()
117 {
118 char* str = tiny_clipread(NULL);
119 if (str) {
120 printf("The clipboard contains: '%s'\n", str);
121 free(str);
122 }
123 else {
124 printf("No text in clipboard.\n");
125 }
126
127 return 0;
128 }
129 ~~~~~~~~~~~~~~~~~~~~
130
131 Writing is a little more difficult especially on X11 systems. Refer to
132 the tiny_clipwrite(3) and tiny_clipnwrite(3) manpages.
133
134 Documentation
135 -------------
136
137 Full and detailed documentation of the functions provided by the
138 tinyclipboard library is available in form of manpages in the `man/`
139 directory of the source tree. Each function is described in detail,
140 usually with examples.
141
142 Contact information
143 -------------------
144
145 The tinyclipboard library was written by Marvin Gülker
146 <m-guelker@guelkerdev.de>. Its project website is
147 <http://www.guelkerdev.de/projects/tinyclipboard/>.
148
149 If you find any bugs or want to contribute to the tinyclipboard
150 library, feel free to contact me under this email address.
151
152 There’s also a discussion mailinglist available. Refer to
153 <http://www.guelkerdev.de/projects/mailinglist/> for subscription
154 information.
155
156 Licensing
157 ---------
158
159 For normal use, I offer the tinyclipboard library under the terms of
160 the GNU GPLv3+ license. For other licensing options, please contact me
161 under the email address mentioned above.
162
163 ### GPL statement
164
165 tinyclipboard is a cross-platform clipboard library written in C.
166 Copyright © 2016 Marvin Gülker
167
168 This program is free software: you can redistribute it and/or modify
169 it under the terms of the GNU General Public License as published by
170 the Free Software Foundation, either version 3 of the License, or
171 (at your option) any later version.
172
173 This program is distributed in the hope that it will be useful,
174 but WITHOUT ANY WARRANTY; without even the implied warranty of
175 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
176 GNU General Public License for more details.
177
178 You should have received a copy of the GNU General Public License
179 along with this program. If not, see <http://www.gnu.org/licenses/>.