Debian Codegraph @

Documentation/Overview/adding_resources.xml

raw
1 <xml>
2 <head>
3 <title>Custom Resource Types</title>
4 </head>
5 <body>
6
7 <p>Extending the resource management system to incorporate a new resource type can be tricky,
8 but with a little guidance, it is fairly straight forward. </p>
9
10 <h3>Intoduction</h3>
11 <p>For this tutorial we will be using a simple class called Object</p>
12
13 <code>
14 class Object
15 {
16 public:
17 Object();
18 Object(int x, int y);
19 int x;
20 int y;
21 };
22 </code>
23
24 <h3>Modifing the class</h3>
25 <p>First you will need to add a constructor that will load from the resource management system and an instance of <codelink>CL_Resource</codelink> to store our resource information in.</p>
26
27 <code>
28 class Object
29 {
30 public:
31 Object();
32 Object(int x, int y);
33 Object(const std::string &resource_id, CL_ResourceManager *manager);
34 int x;
35 int y;
36
37 private:
38 CL_Resource resource;
39 };
40 </code>
41
42 <h3>Creating your resourcedata class</h3>
43 <p>Now, before we actually define our new constructor for Object, lets create our new <codelinke> CL_ResourceData</codelink> derivative class that will actually do the loading. This class is also fairly simple; it needs a constructor that takes a <codelink>CL_Resource</codelink> and two functions: on_load() and on_unload(). These functions will be called by the resource manager when the resource is loaded and unloaded respectively.</p>
44
45 <code>
46 class CL_ResourceData_Object : public CL_ResourceData
47 {
48 public:
49 ResourceData_Object(CL_Resource &resource);
50 virtual ~ResourceData_Object();
51 Object &get_object();
52 private:
53 void on_load();
54 void on_unload();
55 Object object;
56 };
57 </code>
58
59 <p>The constructor tells the resource to attach the data through this instance of CL_ResourceData. Later when you ask your resource manager to load the object it will call the on_load() function which actually reads in your data. Notice that the call to get_attribute takes two parameters in this instance. The first is obviously the variable name, but the second is the default value which is used when the attribute is not found.</p>
60 <code>
61 ResourceData_Object::ResourceData_Object(CL_Resource &resource)
62 : CL_ResourceData(resource)
63 {
64 resource.attach_data("object", this);
65 }
66 ResourceData_Object::on_load()
67 {
68 CL_Resource resource = get_resource();
69 int x = atoi( (resource.get_element().get_attribute("x","50")).c_str() );
70 int y = atoi( (resource.get_element().get_attribute("y","75")).c_str() );
71
72 object.x = x;
73 object.y = y;
74 }
75 ResourceData_Object::on_unload()
76 {
77 object = Object();
78 }
79 </code>
80
81 <h3>The callback function</h3>
82 <p>In order for this to work, we have to create a custom callback function to load your new resource types. The callback function just looks to see if the new resource is of our custom type, and in that event creates a new instance of our resourcedata type.</p>
83
84 <code>
85 static void resource_added(CL_Resource &resource)
86 {
87 std::string type = resource.get_type();
88
89 if (type == "object") new ResourceData_Object(resource);
90 }
91 </code>
92 <p>And then in your initialization routines just add a line like:</p>
93 <code>
94 CL_Slot slot_resource_added - CL_ResourceManager::sig_resource_added().connect(&resource_added);
95 </code>
96
97 <h3>Adding object's constructor</h3>
98 <p>Now just add that constructor for Object that we nearly forgot about. This function will just ask the our <codelink>CL_ResourceManager</codelink> for the instance of our object, then we tell it load it up. Then just get our our data from the resource, but if it returns no data then the name you specified is not of type Object. Then just get out your data however you like, a copy constuctor or overloaded = operator comes in real handy here.</p>
99
100 <code>
101 Object::Object(const std::string &resource_id, CL_ResourceManager *manager)
102 {
103 resource = manager->get_resource(resource_id);
104 resource.load();
105
106 ResourceData_Object *data =
107 (ResourceData_Object *) resource.get_data("object");
108
109 if(!data)
110 throw CL_Error("Resource '" + resource_id + "' is not of type 'object'");
111
112 x = data->get_object().x;
113 y = data->get_object().y;
114
115 resource.unload();
116 }
117 </code>
118
119 <h3>Finale</h3>
120 <p>The last thing to do is to call your resource. For a resource file looking like:</p>
121
122 <code>
123 &lt;resources&gt;
124 &lt;object name="object01" x="20" y="20" /&gt;
125 &lt;/resources&gt;
126 </code>
127 <p>Just create your object like this:</p>
128
129 <code>
130 Object *my_object = new Object("object01", new CL_ResourceManager("my_resourcefile.xml"));
131 </code>
132
133 Thats it!
134
135 <h3>TODO:</h3>
136 <list>
137 <li>Explain how to use the resource manager's provider to load files.</li>
138 <li>Explain how to make the resource manager cache objects.</li>
139 </list>
140 </body>
141 </xml>