Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Merge pull request #52 from obviousjim/master

ofDirectory documentation
  • Loading branch information...
commit f1e50e3e362c19005ed72f623a1bbc163170463c 2 parents a2d6456 + fd29272
Kyle McDonald kylemcdonald authored

Showing 1 changed file with 78 additions and 46 deletions. Show diff stats Hide diff stats

  1. +78 46 _documentation/utils/ofDirectory.markdown
124 _documentation/utils/ofDirectory.markdown
Source Rendered
@@ -2,10 +2,24 @@
2 2
3 3
4 4 ##Description
  5 +ofDirectory is a class for reading and manipulating directories on the file system through openFrameworks.
5 6
  7 +Here is a common way to use it:
6 8
  9 +~~~~{.cpp}
  10 +//some path, may be absolute or relative to bin/data
  11 +string path = "/my/path/file";
  12 +ofDirectory dir(path);
  13 +//only show png files
  14 +dir.allowExt("png");
  15 +//populate the directory object
  16 +dir.listDir();
7 17
8   -
  18 +//go through and print out all the paths
  19 +for(int i = 0; i < dir.numFiles(); i++){
  20 + ofLogNotice(dir.getPath(i));
  21 +}
  22 +~~~~
9 23
10 24 ##Methods
11 25
@@ -31,7 +45,7 @@ _advanced: False_
31 45
32 46 _description: _
33 47
34   -
  48 +Constructs an empty directory object.
35 49
36 50
37 51
@@ -59,7 +73,7 @@ _advanced: False_
59 73
60 74 _description: _
61 75
62   -
  76 +Constructs a directory object and calls open() on the provided path. The contents of the path are not accessible until listDir() is called.
63 77
64 78
65 79
@@ -87,10 +101,9 @@ _advanced: False_
87 101
88 102 _description: _
89 103
  104 +Opens a path. At this point you can see if the directory exists by calling exists() but the contents of the path are not accessible until listDir() is called.
90 105
91   -
92   -
93   -
  106 +
94 107
95 108
96 109 <!----------------------------------------------------------------------------->
@@ -116,7 +129,7 @@ _advanced: False_
116 129 _description: _
117 130
118 131
119   -
  132 +Closes the directory.
120 133
121 134
122 135
@@ -143,9 +156,18 @@ _advanced: False_
143 156
144 157 _description: _
145 158
  159 +Creates the directory if it doesn't exist already. A common reason to use create is to ensure that you are able to write files to a known path, like so
146 160
  161 +~~~~{.cpp}
  162 +string path = "/path/to/file";
  163 +ofDirectory dir(path);
  164 +if(!dir.exists()){
  165 + dir.create(true);
  166 +}
  167 +//now you can be sure that path exists
  168 +~~~~
147 169
148   -
  170 +The recursive boolean flag will indicate if you'd like to create directories all the directories required to reach the given path. In our example, if "/path/to" didn't already exist, the call to create() would also create these. If recursive were set to false, the directory would not be created.
149 171
150 172
151 173
@@ -171,7 +193,7 @@ _advanced: False_
171 193
172 194 _description: _
173 195
174   -
  196 +Returns true if the open directory exists. Great to be used in conjunction with ofDirectory::create()
175 197
176 198
177 199
@@ -199,7 +221,7 @@ _advanced: False_
199 221
200 222 _description: _
201 223
202   -
  224 +Returns the currently opened path.
203 225
204 226
205 227
@@ -227,7 +249,7 @@ _advanced: False_
227 249
228 250 _description: _
229 251
230   -
  252 +Returns true if the open directory can be read.
231 253
232 254
233 255
@@ -255,8 +277,7 @@ _advanced: False_
255 277
256 278 _description: _
257 279
258   -
259   -
  280 +Returns true if the open directory can be written to.
260 281
261 282
262 283
@@ -283,7 +304,7 @@ _advanced: False_
283 304
284 305 _description: _
285 306
286   -
  307 +Returns true if the current directory is executable. An executable directory can be entered into with command such as cd.
287 308
288 309
289 310
@@ -311,7 +332,7 @@ _advanced: False_
311 332
312 333 _description: _
313 334
314   -
  335 +Returns true if the given path is actually a directory.
315 336
316 337
317 338
@@ -339,7 +360,7 @@ _advanced: False_
339 360
340 361 _description: _
341 362
342   -
  363 +Returns true if the directory is hidden in the file system.
343 364
344 365
345 366
@@ -367,7 +388,7 @@ _advanced: False_
367 388
368 389 _description: _
369 390
370   -
  391 +Enables or disables writeable on the current open directory.
371 392
372 393
373 394
@@ -395,6 +416,7 @@ _advanced: False_
395 416
396 417 _description: _
397 418
  419 +Enables or disables readable on the current open directory.
398 420
399 421
400 422
@@ -423,6 +445,7 @@ _advanced: False_
423 445
424 446 _description: _
425 447
  448 +Enables or disables execution on the current open directory. If the directory is executable then it can be entered through commands such as cd.
426 449
427 450
428 451
@@ -451,7 +474,7 @@ _advanced: False_
451 474
452 475 _description: _
453 476
454   -
  477 +Sets whether or not the call to listDir() will return hidden files.
455 478
456 479
457 480
@@ -479,7 +502,7 @@ _advanced: False_
479 502
480 503 _description: _
481 504
482   -
  505 +Copies the directory into path. If bRelativeToData is set to false then path should be absolute. If overwrite is set to true any existing files with the same name will be overwritten by the copy.
483 506
484 507
485 508
@@ -507,6 +530,7 @@ _advanced: False_
507 530
508 531 _description: _
509 532
  533 +Moves the directory into another directory at path. If bRelativeToData is set to false then path should be absolute. If overwrite is set to true any existing files with the same name will be overwritten by the move.
510 534
511 535
512 536
@@ -535,6 +559,7 @@ _advanced: False_
535 559
536 560 _description: _
537 561
  562 +Renames the directory to the path path. If bRelativeToData is set to false then path should be absolute. If overwrite is set to true any existing files with the same name will be overwritten by the rename.
538 563
539 564
540 565
@@ -563,7 +588,7 @@ _advanced: False_
563 588
564 589 _description: _
565 590
566   -
  591 +Deletes the directory. If recursive is set to false and this directory contains others the remove will fail.
567 592
568 593
569 594
@@ -591,11 +616,18 @@ _advanced: False_
591 616
592 617 _description: _
593 618
  619 +Adds an allowed extension to the list of filters when listing directories. Use this to set any number of filters before calling listDir().
594 620
  621 +For example if you wanted to only get images in a directory, you may set several filters:
595 622
596   -
597   -
598   -
  623 +~~~~{.cpp}
  624 +string path = "/path/to/images";
  625 +ofDirectory dir(path);
  626 +dir.allowExt("png");
  627 +dir.allowExt("jpg");
  628 +dir.allowExt("gif");
  629 +dir.listDir();
  630 +~~~~
599 631
600 632 <!----------------------------------------------------------------------------->
601 633
@@ -619,7 +651,7 @@ _advanced: False_
619 651
620 652 _description: _
621 653
622   -
  654 +Opens and populates the directory with files. Returns the number of files found.
623 655
624 656
625 657
@@ -647,6 +679,7 @@ _advanced: False_
647 679
648 680 _description: _
649 681
  682 +Populates the directory with files. Call this after opening a directory and setting filters. After this call, size(), getPath(position), and getName(position) can be used to access the contents of the directory.
650 683
651 684
652 685
@@ -675,7 +708,7 @@ _advanced: False_
675 708
676 709 _description: _
677 710
678   -
  711 +Returns the file name,(eg "mypicture.png") with extension but not the enclosing path at a given index. Position must be less than the result of numFiles().
679 712
680 713
681 714
@@ -703,7 +736,7 @@ _advanced: False_
703 736
704 737 _description: _
705 738
706   -
  739 +Returns the absolute path,(eg "/path/to/files/mypicture.png"). Position must be less than the result of size().
707 740
708 741
709 742
@@ -731,6 +764,7 @@ _advanced: False_
731 764
732 765 _description: _
733 766
  767 +Opens and returns an ofFile object at position. Mode determines how you may interact with the file, the options being: Reference,ofFile::ReadOnly, ofFile::WriteOnly, ofFile::ReadWrite, ofFile::Append
734 768
735 769
736 770
@@ -759,7 +793,7 @@ _advanced: False_
759 793
760 794 _description: _
761 795
762   -
  796 +Returns a vector of ofFile objects populated by a prior call to listDir(). The files are opened in ofFile::Reference mode.
763 797
764 798
765 799
@@ -787,7 +821,7 @@ _advanced: False_
787 821
788 822 _description: _
789 823
790   -
  824 +Operator for accessing files with array notation syntax. Call is equivalent to ofFile::getFile(position).
791 825
792 826
793 827
@@ -815,7 +849,7 @@ _advanced: False_
815 849
816 850 _description: _
817 851
818   -
  852 +Returns if hidden files are set to be shown or not.
819 853
820 854
821 855
@@ -843,7 +877,7 @@ _advanced: False_
843 877
844 878 _description: _
845 879
846   -
  880 +Resets the current directory. Equivalent to close().
847 881
848 882
849 883
@@ -871,7 +905,7 @@ _advanced: False_
871 905
872 906 _description: _
873 907
874   -
  908 +Sorts the contents of the directory by filename.
875 909
876 910
877 911
@@ -899,7 +933,7 @@ _advanced: False_
899 933
900 934 _description: _
901 935
902   -
  936 +Returns the number of files contained within the directory. Set after listDir() is called.
903 937
904 938
905 939
@@ -927,7 +961,7 @@ _advanced: False_
927 961
928 962 _description: _
929 963
930   -
  964 +deprecated. Use size().
931 965
932 966
933 967
@@ -955,7 +989,7 @@ _advanced: False_
955 989
956 990 _description: _
957 991
958   -
  992 +Accessor to low-level poco file object.
959 993
960 994
961 995
@@ -983,7 +1017,7 @@ _advanced: False_
983 1017
984 1018 _description: _
985 1019
986   -
  1020 +Returns true if this directory and another have the same path.
987 1021
988 1022
989 1023
@@ -1011,7 +1045,7 @@ _advanced: False_
1011 1045
1012 1046 _description: _
1013 1047
1014   -
  1048 +Returns true if this directory and another have different paths.
1015 1049
1016 1050
1017 1051
@@ -1039,7 +1073,7 @@ _advanced: False_
1039 1073
1040 1074 _description: _
1041 1075
1042   -
  1076 +Returns true if the right hand side directory is alphabetically after the left hand side directory.
1043 1077
1044 1078
1045 1079
@@ -1067,6 +1101,7 @@ _advanced: False_
1067 1101
1068 1102 _description: _
1069 1103
  1104 +Returns true if the right hand side directory is alphabetically after or equal to the left hand side directory.
1070 1105
1071 1106
1072 1107
@@ -1095,6 +1130,7 @@ _advanced: False_
1095 1130
1096 1131 _description: _
1097 1132
  1133 +Returns true if the left hand side directory is alphabetically after the right hand side directory.
1098 1134
1099 1135
1100 1136
@@ -1123,7 +1159,7 @@ _advanced: False_
1123 1159
1124 1160 _description: _
1125 1161
1126   -
  1162 +Returns true if the left hand side directory is alphabetically after or equal to the right hand side directory;
1127 1163
1128 1164
1129 1165
@@ -1151,7 +1187,7 @@ _advanced: False_
1151 1187
1152 1188 _description: _
1153 1189
1154   -
  1190 +Static method to create a directory at a given path.
1155 1191
1156 1192
1157 1193
@@ -1179,7 +1215,7 @@ _advanced: False_
1179 1215
1180 1216 _description: _
1181 1217
1182   -
  1218 +Returns true if the directory at dirPath is empty.
1183 1219
1184 1220
1185 1221
@@ -1207,8 +1243,7 @@ _advanced: False_
1207 1243
1208 1244 _description: _
1209 1245
1210   -
1211   -
  1246 +Returns true if the directory at dirPath exists.
1212 1247
1213 1248
1214 1249
@@ -1235,7 +1270,7 @@ _advanced: False_
1235 1270
1236 1271 _description: _
1237 1272
1238   -
  1273 +Removes a directory. If deleteIfNotEmpty is set to false and the directory contains files the call will fail.
1239 1274
1240 1275
1241 1276
@@ -1266,9 +1301,6 @@ _description: _
1266 1301
1267 1302
1268 1303
1269   -
1270   -
1271   -
1272 1304 <!----------------------------------------------------------------------------->
1273 1305
1274 1306 ###ofFile getFile(position, mode = ofFile

0 comments on commit f1e50e3

Please sign in to comment.
Something went wrong with that request. Please try again.