From 9dd276bfd1ee270b694bf629807030879baa1ed3 Mon Sep 17 00:00:00 2001 From: Krzysztof Foltman Date: Wed, 2 Aug 2006 20:33:26 +0200 Subject: [PATCH] riched20: Added short descriptions to functions in run.c, just in case anybody had any doubts about what they actually do. --- dlls/riched20/run.c | 194 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 190 insertions(+), 4 deletions(-) diff --git a/dlls/riched20/run.c b/dlls/riched20/run.c index f5ea660fbf9..a2c121a3147 100644 --- a/dlls/riched20/run.c +++ b/dlls/riched20/run.c @@ -27,6 +27,11 @@ WINE_DEFAULT_DEBUG_CHANNEL(richedit); WINE_DECLARE_DEBUG_CHANNEL(richedit_check); WINE_DECLARE_DEBUG_CHANNEL(richedit_lists); +/****************************************************************************** + * ME_CanJoinRuns + * + * Returns 1 if two runs can be safely merged into one, 0 otherwise. + */ int ME_CanJoinRuns(ME_Run *run1, ME_Run *run2) { if ((run1->nFlags | run2->nFlags) & MERF_NOJOIN) @@ -45,8 +50,18 @@ void ME_SkipAndPropagateCharOffset(ME_DisplayItem *p, int shift) ME_PropagateCharOffset(p, shift); } +/****************************************************************************** + * ME_PropagateCharOffsets + * + * Shifts (increases or decreases) character offset (relative to beginning of + * the document) of the part of the text starting from given place. + */ void ME_PropagateCharOffset(ME_DisplayItem *p, int shift) { + /* Runs in one paragraph contain character offset relative to their owning + * paragraph. If we start the shifting from the run, we need to shift + * all the relative offsets until the end of the paragraph + */ if (p->type == diRun) /* propagate in all runs in this para */ { TRACE("PropagateCharOffset(%s, %d)\n", debugstr_w(p->member.run.strText->szData), shift); @@ -56,6 +71,10 @@ void ME_PropagateCharOffset(ME_DisplayItem *p, int shift) p = ME_FindItemFwd(p, diRunOrParagraphOrEnd); } while(p->type == diRun); } + /* Runs in next paragraphs don't need their offsets updated, because they, + * again, those offsets are relative to their respective paragraphs. + * Instead of that, we're updating paragraphs' character offsets. + */ if (p->type == diParagraph) /* propagate in all next paras */ { do { @@ -64,6 +83,9 @@ void ME_PropagateCharOffset(ME_DisplayItem *p, int shift) p = p->member.para.next_para; } while(p->type == diParagraph); } + /* diTextEnd also has character offset in it, which makes finding text length + * easier. But it needs to be up to date first. + */ if (p->type == diTextEnd) { p->member.para.nCharOfs += shift; @@ -71,6 +93,11 @@ void ME_PropagateCharOffset(ME_DisplayItem *p, int shift) } } +/****************************************************************************** + * ME_CheckCharOffsets + * + * Checks if editor lists' validity and optionally dumps the document structure + */ void ME_CheckCharOffsets(ME_TextEditor *editor) { ME_DisplayItem *p = editor->pBuffer->pFirst; @@ -111,6 +138,13 @@ void ME_CheckCharOffsets(ME_TextEditor *editor) } while(1); } +/****************************************************************************** + * ME_CharOfsFromRunOfs + * + * Converts a character position relative to the start of the run, to a + * character position relative to the start of the document. + * Kind of a "local to global" offset conversion. + */ int ME_CharOfsFromRunOfs(ME_TextEditor *editor, ME_DisplayItem *pRun, int nOfs) { ME_DisplayItem *pPara; @@ -125,11 +159,25 @@ int ME_CharOfsFromRunOfs(ME_TextEditor *editor, ME_DisplayItem *pRun, int nOfs) + ME_VPosToPos(pRun->member.run.strText, nOfs); } +/****************************************************************************** + * ME_CursorFromCharOfs + * + * Converts a character offset (relative to the start of the document) to + * a cursor structure (which contains a run and a position relative to that + * run). + */ void ME_CursorFromCharOfs(ME_TextEditor *editor, int nCharOfs, ME_Cursor *pCursor) { ME_RunOfsFromCharOfs(editor, nCharOfs, &pCursor->pRun, &pCursor->nOffset); } +/****************************************************************************** + * ME_RunOfsFromCharOfs + * + * Find a run and relative character offset given an absolute character offset + * (absolute offset being an offset relative to the start of the document). + * Kind of a "global to local" offset conversion. + */ void ME_RunOfsFromCharOfs(ME_TextEditor *editor, int nCharOfs, ME_DisplayItem **ppRun, int *pOfs) { ME_DisplayItem *pPara; @@ -176,6 +224,11 @@ void ME_RunOfsFromCharOfs(ME_TextEditor *editor, int nCharOfs, ME_DisplayItem ** assert((*ppRun)->member.run.nFlags & MERF_ENDPARA); } +/****************************************************************************** + * ME_JoinRuns + * + * Merges two adjacent runs, the one given as a parameter and the next one. + */ void ME_JoinRuns(ME_TextEditor *editor, ME_DisplayItem *p) { ME_DisplayItem *pNext = p->next; @@ -184,8 +237,11 @@ void ME_JoinRuns(ME_TextEditor *editor, ME_DisplayItem *p) assert(p->member.run.nCharOfs != -1); ME_GetParagraph(p)->member.para.nFlags |= MEPF_REWRAP; - if (editor->bCaretAtEnd && editor->pCursors[0].pRun == pNext) + /* if we were at the end of screen line, and the next run is in the new + * line, then it's not the end of the line anymore */ + if (editor->bCaretAtEnd && editor->pCursors[0].pRun == pNext) editor->bCaretAtEnd = FALSE; + /* Update all cursors so that they don't contain the soon deleted run */ for (i=0; inCursors; i++) { if (editor->pCursors[i].pRun == pNext) { editor->pCursors[i].pRun = p; @@ -205,6 +261,12 @@ void ME_JoinRuns(ME_TextEditor *editor, ME_DisplayItem *p) } } +/****************************************************************************** + * ME_SplitRun + * + * Splits a run into two in a given place. It also updates the screen position + * and size (extent) of the newly generated runs. + */ ME_DisplayItem *ME_SplitRun(ME_Context *c, ME_DisplayItem *item, int nVChar) { ME_TextEditor *editor = c->editor; @@ -248,7 +310,12 @@ ME_DisplayItem *ME_SplitRun(ME_Context *c, ME_DisplayItem *item, int nVChar) return item2; } -/* split a run starting from voffset */ +/****************************************************************************** + * ME_SplitRunSimple + * + * Does the most basic job of splitting a run into two - it does not + * update the positions and extents. + */ ME_DisplayItem *ME_SplitRunSimple(ME_TextEditor *editor, ME_DisplayItem *item, int nVChar) { ME_Run *run = &item->member.run; @@ -283,6 +350,11 @@ ME_DisplayItem *ME_SplitRunSimple(ME_TextEditor *editor, ME_DisplayItem *item, i return item2; } +/****************************************************************************** + * ME_MakeRun + * + * A helper function to create run structures quickly. + */ ME_DisplayItem *ME_MakeRun(ME_Style *s, ME_String *strData, int nFlags) { ME_DisplayItem *item = ME_MakeDI(diRun); @@ -294,7 +366,11 @@ ME_DisplayItem *ME_MakeRun(ME_Style *s, ME_String *strData, int nFlags) return item; } - +/****************************************************************************** + * ME_InsertRun + * + * Inserts a run at a given character position (offset). + */ ME_DisplayItem *ME_InsertRun(ME_TextEditor *editor, int nCharOfs, ME_DisplayItem *pItem) { ME_Cursor tmp; @@ -311,6 +387,13 @@ ME_DisplayItem *ME_InsertRun(ME_TextEditor *editor, int nCharOfs, ME_DisplayItem return pDI; } +/****************************************************************************** + * ME_InsertRunAtCursor + * + * Inserts a new run with given style, flags and content at a given position, + * which is passed as a cursor structure (which consists of a run and + * a run-relative character offset). + */ ME_DisplayItem * ME_InsertRunAtCursor(ME_TextEditor *editor, ME_Cursor *cursor, ME_Style *style, const WCHAR *str, int len, int flags) @@ -319,6 +402,8 @@ ME_InsertRunAtCursor(ME_TextEditor *editor, ME_Cursor *cursor, ME_Style *style, ME_UndoItem *pUI; if (cursor->nOffset) { + /* We're inserting at the middle of the existing run, which means that + * that run must be split. It isn't always necessary, but */ cursor->pRun = ME_SplitRunSimple(editor, cursor->pRun, cursor->nOffset); cursor->nOffset = 0; } @@ -339,6 +424,13 @@ ME_InsertRunAtCursor(ME_TextEditor *editor, ME_Cursor *cursor, ME_Style *style, return pDI; } +/****************************************************************************** + * ME_UpdateRunFlags + * + * Determine some of run attributes given its content (style, text content). + * Some flags cannot be determined by this function (MERF_GRAPHICS, + * MERF_ENDPARA) + */ void ME_UpdateRunFlags(ME_TextEditor *editor, ME_Run *run) { assert(run->nCharOfs != -1); @@ -375,6 +467,12 @@ void ME_UpdateRunFlags(ME_TextEditor *editor, ME_Run *run) run->nFlags &= ~(MERF_WHITESPACE | MERF_STARTWHITE | MERF_ENDWHITE); } +/****************************************************************************** + * ME_GetGraphicsSize + * + * Sets run extent for graphics runs. This functionality is just a placeholder + * for future OLE object support, and will be removed. + */ void ME_GetGraphicsSize(ME_TextEditor *editor, ME_Run *run, SIZE *pSize) { assert(run->nFlags & MERF_GRAPHICS); @@ -382,6 +480,13 @@ void ME_GetGraphicsSize(ME_TextEditor *editor, ME_Run *run, SIZE *pSize) pSize->cy = 64; } +/****************************************************************************** + * ME_CharFromPoint + * + * Returns a character position inside the run given a run-relative + * pixel horizontal position. This version rounds left (ie. if the second + * character is at pixel position 8, then for cx=0..7 it returns 0). + */ int ME_CharFromPoint(ME_TextEditor *editor, int cx, ME_Run *run) { int fit = 0; @@ -393,7 +498,7 @@ int ME_CharFromPoint(ME_TextEditor *editor, int cx, ME_Run *run) if (run->nFlags & (MERF_TAB | MERF_CELL)) { - if (cx < run->nWidth/2) + if (cx < run->nWidth/2) return 0; return 1; } @@ -414,6 +519,17 @@ int ME_CharFromPoint(ME_TextEditor *editor, int cx, ME_Run *run) return fit; } +/****************************************************************************** + * ME_CharFromPointCursor + * + * Returns a character position inside the run given a run-relative + * pixel horizontal position. This version rounds to the nearest character edge + * (ie. if the second character is at pixel position 8, then for cx=0..3 + * it returns 0, and for cx=4..7 it returns 1). + * + * It is used for mouse click handling, for better usability (and compatibility + * with the native control). + */ int ME_CharFromPointCursor(ME_TextEditor *editor, int cx, ME_Run *run) { int fit = 0, fit1 = 0; @@ -457,6 +573,12 @@ int ME_CharFromPointCursor(ME_TextEditor *editor, int cx, ME_Run *run) return fit; } +/****************************************************************************** + * ME_PointFromChar + * + * Returns a run-relative pixel position given a run-relative character + * position (character offset) + */ int ME_PointFromChar(ME_TextEditor *editor, ME_Run *pRun, int nOffset) { SIZE size; @@ -476,6 +598,11 @@ int ME_PointFromChar(ME_TextEditor *editor, ME_Run *pRun, int nOffset) return size.cx; } +/****************************************************************************** + * ME_GetTextExtent + * + * Finds a width and a height of the text using a specified style + */ void ME_GetTextExtent(ME_Context *c, LPCWSTR szText, int nChars, ME_Style *s, SIZE *size) { @@ -486,6 +613,12 @@ void ME_GetTextExtent(ME_Context *c, LPCWSTR szText, int nChars, ME_Style *s, ME_UnselectStyleFont(c->editor, hDC, s, hOldFont); } +/****************************************************************************** + * ME_GetRunSizeCommon + * + * Finds width, height, ascent and descent of a run, up to given character + * (nLen). + */ SIZE ME_GetRunSizeCommon(ME_Context *c, ME_Paragraph *para, ME_Run *run, int nLen, int *pAscent, int *pDescent) { SIZE size; @@ -545,12 +678,25 @@ SIZE ME_GetRunSizeCommon(ME_Context *c, ME_Paragraph *para, ME_Run *run, int nLe return size; } +/****************************************************************************** + * ME_GetRunSize + * + * Finds width and height (but not ascent and descent) of a part of the run + * up to given character. + */ SIZE ME_GetRunSize(ME_Context *c, ME_Paragraph *para, ME_Run *run, int nLen) { int asc, desc; return ME_GetRunSizeCommon(c, para, run, nLen, &asc, &desc); } +/****************************************************************************** + * ME_CalcRunExtent + * + * Updates the size of the run (fills width, ascent and descent). The height + * is calculated based on whole row's ascent and descent anyway, so no need + * to use it here. + */ void ME_CalcRunExtent(ME_Context *c, ME_Paragraph *para, ME_Run *run) { if (run->nFlags & MERF_HIDDEN) @@ -565,12 +711,24 @@ void ME_CalcRunExtent(ME_Context *c, ME_Paragraph *para, ME_Run *run) } } +/****************************************************************************** + * ME_MustBeWrapped + * + * This should ensure that the given paragraph is wrapped so that its screen + * row structure may be used. But it doesn't, yet. + */ void ME_MustBeWrapped(ME_Context *c, ME_DisplayItem *para) { assert(para->type == diParagraph); /* FIXME */ } +/****************************************************************************** + * ME_SetSelectionCharFormat + * + * Applies a style change, either to a current selection, or to insert cursor + * (ie. the style next typed characters will use). + */ void ME_SetSelectionCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt) { int nFrom, nTo; @@ -588,6 +746,11 @@ void ME_SetSelectionCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt) ME_SetCharFormat(editor, nFrom, nTo-nFrom, pFmt); } +/****************************************************************************** + * ME_SetCharFormat + * + * Applies a style change to the specified part of the text + */ void ME_SetCharFormat(ME_TextEditor *editor, int nOfs, int nChars, CHARFORMAT2W *pFmt) { ME_Cursor tmp, tmp2; @@ -632,6 +795,11 @@ void ME_SetCharFormat(ME_TextEditor *editor, int nOfs, int nChars, CHARFORMAT2W } } +/****************************************************************************** + * ME_SetDefaultCharFormat + * + * Applies a style change to the default character style. + */ void ME_SetDefaultCharFormat(ME_TextEditor *editor, CHARFORMAT2W *mod) { ME_Style *style; @@ -658,6 +826,12 @@ void ME_GetRunCharFormat(ME_TextEditor *editor, ME_DisplayItem *run, CHARFORMAT2 ME_CopyCharFormat(pFmt, &run->member.run.style->fmt); } +/****************************************************************************** + * ME_GetDefaultCharFormat + * + * Retrieves the current default character style (the one applied where no + * other style was applied) . + */ void ME_GetDefaultCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt) { int nFrom, nTo; @@ -665,6 +839,12 @@ void ME_GetDefaultCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt) ME_CopyCharFormat(pFmt, &editor->pBuffer->pDefaultStyle->fmt); } +/****************************************************************************** + * ME_GetSelectionCharFormat + * + * If selection exists, it returns all style elements that are set consistently + * in the whole selection. If not, it just returns the current style. + */ void ME_GetSelectionCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt) { int nFrom, nTo; @@ -677,6 +857,12 @@ void ME_GetSelectionCharFormat(ME_TextEditor *editor, CHARFORMAT2W *pFmt) ME_GetCharFormat(editor, nFrom, nTo, pFmt); } +/****************************************************************************** + * ME_GetCharFormat + * + * Returns the style consisting of those attributes which are consistently set + * in the whole character range. + */ void ME_GetCharFormat(ME_TextEditor *editor, int nFrom, int nTo, CHARFORMAT2W *pFmt) { ME_DisplayItem *run, *run_end;