aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 1be0d2c7cc5f35fa2d1c97bcc863e270d887ba74 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

E P I S O D E   B R O W S E R
d o c u m e n t a t i o n

Introduction
~~~~~~~~~~~~
Episode Browser is a simple graphical program that offers an interface
to episodes of TV series stored on the local hard drive. It offers
ways of keeping track of watched and unwatched episodes, as well as
fetching episode information from the internet.

In its current form, it is designed specifically for Detective Conan.

Backend
~~~~~~~
The fundamental features of Episode Browser, such as detecing and
keeping track of local episodes, fetching information from the
internet and interacting with the MPC-HC media player, are implemented
in Prolog (see the pl folder).

At the time of writing, the backend implementation is tightly coupled
to the author's specific system. To be used for anything else than
episodes of Detective Conan stored in a specific folder on the hard
drive, the predicates defined in local_episodes.pl must be modified
and the program recompiled. To fetch episode information from other
sources than Detective Conan World, the episode_data.pl file must be
modified.

Frontend
~~~~~~~~
The graphical interface is implemented in C++ using the Win32 API (see
the c folder). The source code is spread across a small number of
files. In summary:

main.cpp		Entry point and initialization. Contains the main event handler.
listview.*		Creates and handles the shared aspects of the two list views.
episodelistview.*	Defines the interface to the episode list view.
datalistview.*		Defines the interface to the data list view.
layout.*		Handles the placement of child windows.
pl.*			Interface to Prolog backend.
win.*			Helpers for interacting with the Win32 API.
wcharptr.*		Defines WcharPtr, a class that owns a wchar_t*.
util.h			Simple utility functions.
debug.*			Helpers for debugging.

The code operates under the assumption that "raw" pointers are
non-owning -- i.e., their lifetime is managed by somebody else, such
as Windows or Prolog. When strings need to be heap-allocated, like
when converting from a narrow to a wide string, they are put within a
WcharPtr object, which manages the lifetime of the string.

Building
~~~~~~~~
Episode Browser is built with GNU Make. For the build process, the
following additional programs are required:

 - swipl-ld (included with SWI-Prolog)
 - GCC/G++
 - Perl

To build b/EpisodeBrowser.exe, issue `make' in the root directory of
the project.

Hacking
~~~~~~~
The Episode Browser source code uses a limited form of Hungarian
notation. In summary, Hungarian notation is used only for

 - traditional Win32 names such as uMsg, lParam, hWnd,
 - variables of Windows-specific types, like hfNormal (HFONT),
 - arrays, such as vTipCtx (read as: context tip vector),
 - booleans, such as bActive, bViewWatched,
 - counts, such as cb (byte count), cch (character count), and
 - type disambiguation.

For an example of the last point, imagine you have an integer named
`rating', which you want to convert to a string. What should the
string be called? The simple answer is `sRating'.

In addition, global variables are prefixed with g_ and non-public
member variables are prefixed with m_.

A special note on the meaning of cb and cch: these prefixes are used
to designate size. For strings, this means the total size, including
space for the terminating NUL character. To designate string length
without NUL, `len' is used.

While specific Hungarian prefixes are unnecessary for most variables,
"natural" word order should be avoided. In other words, lenString is
preferred over stringLen, because it mirrors vString.