src/bin/rc/docs/librdef.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>The librdef library</TITLE>
   4 </HEAD>
   5 <BODY BGCOLOR="#FFFFFF">
   6
   7 <H1>The librdef library</H1>
   8
   9 <P>Of course, it would be cool if other applications (such as GUI resource editors) could also import and export rdef files. That is why the bulk of rc's functionality is implemented in a separate shared library, librdef.so.</P>
  10
  11 <P>Using the library in your own applications is very simple. Here are some quick instructions to get you started:</P>
  12
  13 <OL>
  14 <LI><CODE>#include "rdef.h"</CODE> in your sources</LI>
  15 <LI>link your app to librdef.so</LI>
  16 </OL>
  17
  18 <P>The API is rather bare-bones, but it gets the job done. The library uses files to transfer data to and from your application. This may seem odd, but it is actually a big advantage. After calling the API functions to compile an rdef file, you can use the standard BResources class to read the resources from the output file. Chances are high that your application already knows how to do this.</P>
  19
  20 <P>To compile a resource file, the steps are typically this:</P>
  21
  22 <OL>
  23
  24 <LI>Call <CODE>rdef_add_include_dir()</CODE> one or more times to add include file search paths.</LI>
  25
  26 <LI>Call <CODE>rdef_add_input_file()</CODE> one or more times to add the rdef files that you want to compile.</LI>
  27
  28 <LI>Call <CODE>rdef_set_flags()</CODE> to toggle compiler options.</LI>
  29
  30 <LI>Call <CODE>rdef_compile()</CODE> with the name of the output file. This performs the actual compilation.</LI>
  31
  32 <LI>Call <CODE>rdef_free_input_files()</CODE> to clear the list of input files that you added earlier.</LI>
  33
  34 <LI>Call <CODE>rdef_free_include_dirs()</CODE> to clear the list of include directories that you added earlier.</LI>
  35
  36 </OL>
  37
  38 <P>Decompiling is very similar, although include directories are not used here:</P>
  39
  40 <OL>
  41
  42 <LI>Call <CODE>rdef_add_input_file()</CODE> one or more times to add the resource files that you want to decompile.</LI>
  43
  44 <LI>Call <CODE>rdef_set_flags()</CODE> to toggle compiler options.</LI>
  45
  46 <LI>Call <CODE>rdef_decompile()</CODE> with the name of the output file. The name of the header file (if any) will be automatically constructed by appending ".h" to the output file name.</LI>
  47
  48 <LI>Call <CODE>rdef_free_input_files()</CODE> to clear the list of input files that you added earlier.</LI>
  49
  50 </OL>
  51
  52 <P>If one of these functions returns something other than B_OK, an error occurred. You can look at the following variables to find out more about the error, and construct meaningul error messages:</P>
  53
  54 <UL>
  55 <LI><CODE>rdef_err</CODE> The error code that was returned.</LI>
  56 <LI><CODE>rdef_err_line</CODE> The line number where compilation failed.</LI>
  57 <LI><CODE>rdef_err_file</CODE> The file where the error occurred.</LI>
  58 <LI><CODE>rdef_err_msg</CODE> The error message from the compiler.</LI>
  59 </UL>
  60
  61 <P>For more information about using librdef, see "rdef.h", which explains the available functions and data structures in more depth. For a real-world example, take a look at "rc.cpp", which contains the complete implementation of the rc compiler. As you'll see, there really isn't much to it, because librdef already does all the work.</P>
  62
  63 </BODY>
  64 </HTML>